Markdown Page Rendering
Relevant source files
The following files were used as context for generating this wiki page:
Markdown Page Rendering transforms static content files into formatted HTML documents using the Astro framework and Tailwind CSS. The system processes Markdown files located in the content directory and applies structured typography styles to ensure accessible and consistent visual presentation.
This module integrates content collections with a typography system that supports multiple font pairings and dark mode themes.
Sources: AGENTS.md:65-67, src/pages/dev/typography.md:1-25
Content Processing and SEO
The system processes Markdown files by extracting frontmatter data and rendering the body content into HTML. A utility function resolves SEO metadata by prioritizing explicit SEO fields over standard frontmatter or rendered content.
The flow shows how metadata is derived from multiple content sources to build the final SEO configuration.
Sources: src/features/pages/pages.utils.ts:59-71
SEO Resolution Logic
The resolvePageSeo function determines the page description and title using a specific hierarchy:
- Description: Prefers
seo.description, then falls back to the page'sdescriptionfield, and finally uses therendered.htmlif available. - Title: Prefers
seo.titleover the standardtitlefield. - Images: Passes through
seo.ogImageif defined.
Sources: src/features/pages/pages.utils.ts:60-71, src/features/pages/pages.utils.test.ts:51-112
Typography System
The project uses the @tailwindcss/typography plugin to style rendered Markdown content. The core styling is applied via the prose class, which targets standard HTML elements like headings, paragraphs, and lists.
Prose Styling Variables
The system defines custom CSS variables within the .prose class to manage colors and weights across light and dark modes.
| Variable | Description | Default (Light) | Dark Mode Value |
|---|---|---|---|
--tw-prose-body | Main text color | var(--color-primary-700) | var(--color-primary-200) |
--tw-prose-headings | Heading text color | var(--color-primary-950) | var(--color-white) |
--tw-prose-links | Link color | var(--color-primary-950) | var(--color-white) |
--tw-prose-pre-bg | Code block background | var(--color-primary-900) | rgb(0 0 0 / 50%) |
--tw-prose-bold | Bold text weight | 800 | N/A |
Sources: src/assets/styles/typography.css:5-64
Font Pairing Integration
Rendered pages apply font families based on data attributes. The typography system supports specific configurations for different "domains" of the site.
- Work/Play/Live: Different pairings (e.g., IBM Plex Sans, Nunito, Source Sans 3) are assigned to the body and headings via
[data-font]attributes. - Global Styles: Headings use a specific
var(--font-heading)while UI elements like headers and footers usevar(--font-ui).
Sources: src/assets/styles/typography.css:94-114, src/components/Settings/Font/pairings.ts:110-136
Content Organization and Filtering
Pages are stored as Markdown files in src/content/pages/. The system employs filters to manage which pages are rendered in navigation and listing views.
Page Entry Structure
A standard Markdown content entry contains the following metadata:
| Field | Type | Description |
|---|---|---|
title | String | The display title of the page. |
order | Number | Optional sorting weight (defaults to 999). |
draft | Boolean | If true, the page is excluded from production builds. |
seo | Object | Nested object for title and description overrides. |
Sources: src/content/pages/index.md:1-9, src/features/pages/pages.utils.ts:4-15, src/features/pages/pages.utils.test.ts:13-25
Filtering and Sorting
The rendering engine utilizes utilities to refine the list of pages:
- Draft Filter:
buildPagesFilterautomatically excludes entries wheredraftistrue. - Index Omission:
omitIndexPageremoves the rootindexpage from general listings. - Sorting:
sortPagesorganizes content by theorderfield first, falling back to an alphabetical title sort.
Sources: src/features/pages/pages.utils.ts:4-57, src/features/pages/pages.utils.test.ts:28-48
Conclusion
Markdown Page Rendering in this project combines Astro's content collections with a robust Tailwind Typography implementation. By centralizing SEO resolution and typography variables, the system ensures that content written in plain Markdown is transformed into accessible, theme-aware, and search-optimized web pages.