From 3ab3c9c82dd365149c7d811924f0f72aa838a390 Mon Sep 17 00:00:00 2001 From: Chizoba Jude Ojini Date: Mon, 16 Nov 2026 12:07:18 +0000 Subject: [PATCH 1/5] feat(guides): keep each guide's details and dates in its own front matter - slug, title, description, order, published and updated live in content/guides/.md, read at build time, so a new guide needs no code change - published and updated are UTC moments; the page shows the time when both fall on one day - site constants move to a plain module so the e2e runner can read them --- .../commonmark-vs-github-flavored-markdown.md | 9 +++ .../guides/markdown-for-devto-and-hashnode.md | 9 +++ content/guides/markdown-images.md | 9 +++ content/guides/markdown-line-breaks.md | 9 +++ content/guides/markdown-math-and-diagrams.md | 9 +++ content/guides/markdown-portability.md | 9 +++ content/guides/obsidian-to-github-markdown.md | 9 +++ docs/SYSTEM_SPEC.md | 2 +- docs/UI_SPEC.md | 2 +- e2e/guides.spec.ts | 14 +++- e2e/legal.spec.ts | 2 +- infra/guide-catalogue-plugin.ts | 22 ++++++ infra/guide-catalogue.ts | 42 ++++++++++ src/env.d.ts | 6 ++ src/lib/site/guides-content.test.ts | 15 ++++ src/lib/site/guides-content.ts | 21 ++++- src/lib/site/guides.test.ts | 19 ++++- src/lib/site/guides.ts | 78 +++---------------- src/lib/site/seo.ts | 16 +--- src/lib/site/site.ts | 18 +++++ src/routes/guides.$slug.tsx | 22 +++++- src/routes/guides.index.tsx | 2 +- vite.config.ts | 2 + vitest.config.ts | 3 +- 24 files changed, 256 insertions(+), 93 deletions(-) create mode 100644 infra/guide-catalogue-plugin.ts create mode 100644 infra/guide-catalogue.ts create mode 100644 src/lib/site/site.ts diff --git a/content/guides/commonmark-vs-github-flavored-markdown.md b/content/guides/commonmark-vs-github-flavored-markdown.md index 3007927..4cbee83 100644 --- a/content/guides/commonmark-vs-github-flavored-markdown.md +++ b/content/guides/commonmark-vs-github-flavored-markdown.md @@ -1,3 +1,12 @@ +--- +slug: commonmark-vs-github-flavored-markdown +title: "CommonMark vs GitHub Flavored Markdown: What Differs" +description: "A clear comparison of CommonMark and GitHub Flavored Markdown: tables, task lists, strikethrough, footnotes, autolinks and alerts, and when each one matters." +order: 2 +published: 2026-11-02T00:00:00Z +updated: 2026-11-02T00:00:00Z +--- + CommonMark and GitHub Flavored Markdown (GFM) are the two Markdown standards you will meet most often. GFM is a strict superset of CommonMark, which means every valid CommonMark document is also valid GFM, but not the other way round. Knowing exactly what GFM adds tells you when your text stops being universally portable. ## What CommonMark is diff --git a/content/guides/markdown-for-devto-and-hashnode.md b/content/guides/markdown-for-devto-and-hashnode.md index 12a2fb9..136799f 100644 --- a/content/guides/markdown-for-devto-and-hashnode.md +++ b/content/guides/markdown-for-devto-and-hashnode.md @@ -1,3 +1,12 @@ +--- +slug: markdown-for-devto-and-hashnode +title: Writing Markdown for dev.to and Hashnode +description: "Tips for writing blog posts in Markdown that publish cleanly to dev.to and Hashnode: front matter, images, code blocks, raw HTML and what to check first." +order: 4 +published: 2026-11-02T00:00:00Z +updated: 2026-11-02T00:00:00Z +--- + dev.to and Hashnode both let you write posts in Markdown, which makes it tempting to draft in your own editor and paste the result. That works well, as long as you know where each platform differs from the Markdown you write locally. This guide covers the habits that make a post publish cleanly the first time. ## Both are Markdown, with their own rules diff --git a/content/guides/markdown-images.md b/content/guides/markdown-images.md index d695d0f..59f3211 100644 --- a/content/guides/markdown-images.md +++ b/content/guides/markdown-images.md @@ -1,3 +1,12 @@ +--- +slug: markdown-images +title: "Markdown Images: Paths, Alt Text and Portability" +description: "How to add images in Markdown so they show up everywhere: relative paths, hosted URLs, base64 data URIs, alt text and the mistakes that break previews." +order: 6 +published: 2026-11-02T00:00:00Z +updated: 2026-11-02T00:00:00Z +--- + Images are the most common reason a Markdown post looks broken after publishing. The text copies perfectly, and then every picture shows as a missing icon. The cause is almost always the path, and the fix is to understand where each kind of image link actually works. ## The basic syntax diff --git a/content/guides/markdown-line-breaks.md b/content/guides/markdown-line-breaks.md index 9164483..48930e4 100644 --- a/content/guides/markdown-line-breaks.md +++ b/content/guides/markdown-line-breaks.md @@ -1,3 +1,12 @@ +--- +slug: markdown-line-breaks +title: Markdown Line Breaks and Paragraphs Explained +description: "How line breaks work in Markdown: paragraphs, soft breaks and hard breaks, why trailing spaces are fragile, and which method renders the same everywhere." +order: 5 +published: 2026-11-02T00:00:00Z +updated: 2026-11-02T00:00:00Z +--- + Line breaks are one of the most confusing parts of Markdown. You press Enter, and nothing happens in the preview, or everything runs together, or it works on one site and not another. The behavior is actually well defined, and once you know the rules you can pick the method that survives every platform. ## Paragraphs, soft breaks and hard breaks diff --git a/content/guides/markdown-math-and-diagrams.md b/content/guides/markdown-math-and-diagrams.md index 66fa199..6abb0ef 100644 --- a/content/guides/markdown-math-and-diagrams.md +++ b/content/guides/markdown-math-and-diagrams.md @@ -1,3 +1,12 @@ +--- +slug: markdown-math-and-diagrams +title: "Math and Mermaid Diagrams in Markdown: Where They Work" +description: "Where LaTeX math and Mermaid diagrams render in Markdown: GitHub and Obsidian support them, other platforms do not. How to write them and what to do instead." +order: 7 +published: 2026-11-02T00:00:00Z +updated: 2026-11-02T00:00:00Z +--- + LaTeX math and Mermaid diagrams are two of the most useful extensions to Markdown, and two of the least portable. They render beautifully on some platforms and show up as raw source on others. This guide shows how to write them and where they work, so you can decide when to use them. ## Math in Markdown diff --git a/content/guides/markdown-portability.md b/content/guides/markdown-portability.md index f2dc8bf..67a5d51 100644 --- a/content/guides/markdown-portability.md +++ b/content/guides/markdown-portability.md @@ -1,3 +1,12 @@ +--- +slug: markdown-portability +title: "Portable Markdown: Why It Renders Differently Everywhere" +description: Why the same Markdown looks different on GitHub, dev.to and Obsidian, and a checklist for making your writing render the same on every platform. +order: 1 +published: 2026-11-02T00:00:00Z +updated: 2026-11-02T00:00:00Z +--- + Markdown looks like one language, but it is really a family of dialects. The same file can render perfectly on GitHub, lose a diagram on dev.to and print raw brackets in a static site generator. This guide explains why that happens and gives you a checklist for writing Markdown that renders the same everywhere. ## Why the same Markdown renders differently diff --git a/content/guides/obsidian-to-github-markdown.md b/content/guides/obsidian-to-github-markdown.md index cc150a2..8f47249 100644 --- a/content/guides/obsidian-to-github-markdown.md +++ b/content/guides/obsidian-to-github-markdown.md @@ -1,3 +1,12 @@ +--- +slug: obsidian-to-github-markdown +title: "Obsidian to GitHub Markdown: Wiki-links, Callouts & More" +description: "How to share Obsidian notes outside Obsidian: convert wiki-links, highlights, callouts and embeds so they render on GitHub, dev.to and static sites." +order: 3 +published: 2026-11-02T00:00:00Z +updated: 2026-11-02T00:00:00Z +--- + Obsidian stores notes as plain Markdown files, which makes them easy to share, but Obsidian adds syntax that other tools do not understand. If you copy a note straight into a GitHub README, a dev.to post or a static site, some of it will break. This guide lists what to convert and how. ## What Obsidian adds to Markdown diff --git a/docs/SYSTEM_SPEC.md b/docs/SYSTEM_SPEC.md index f228335..6e881a1 100644 --- a/docs/SYSTEM_SPEC.md +++ b/docs/SYSTEM_SPEC.md @@ -775,5 +775,5 @@ CREATE TABLE share_comments ( -- plain text, one level of replies - **IndexNow:** `public/.txt` proves site ownership; the release workflow runs `scripts/indexnow.ts` after each deploy (non-blocking). - **Assets:** `public/og.png` (1200x630) and the app icons are generated by `bun run brand` from `public/favicon.svg`; `public/manifest.webmanifest` describes the installable app. - **Checked by:** `src/lib/site/seo.test.ts` and `e2e/seo.spec.ts`. -- **Guides:** long-form articles live in `content/guides/.md` (no H1; the page title is the H1) with their metadata (title, description, dates) in `src/lib/site/guides.ts`. The `/guides` index and `/guides/$slug` pages render them with mdstudio's own pipeline (`renderMarkdown`, sanitized), add `TechArticle` and `BreadcrumbList` JSON-LD, an "On this page" table of contents and per-guide sitemap `lastmod`. `src/lib/site/guides.test.ts` enforces the invariants: a file per guide, title at most 60 and description 110 to 160 characters, at least three sections, no checker issues on the GitHub, dev.to and Obsidian profiles, and every guide listed in `public/llms.txt`. To add a guide: write the Markdown, add its metadata, add it to `llms.txt`. +- **Guides:** long-form articles live in `content/guides/.md` (no H1; the page title is the H1) and say what they are in their own front matter: `slug` (the file name), `title`, `description`, `order` (where they sit in the lists; lower first, guides without one follow newest first), and `published` and `updated` as UTC moments (`2026-11-02T09:00:00Z`, so two changes on one day can be told apart; the page shows the time when both fall on the same day). `infra/guide-catalogue.ts` reads that front matter (plain Node, shared by the build, the tests and the e2e runner) and `infra/guide-catalogue-plugin.ts` hands it to `src/lib/site/guides.ts` as the `virtual:guide-catalogue` module, so lists, the sitemap and structured data never load guide text and the page strips the front matter before rendering. The `/guides` index and `/guides/$slug` pages render the text with mdstudio's own pipeline (`renderMarkdown`, sanitized), add `TechArticle` and `BreadcrumbList` JSON-LD, an "On this page" table of contents and per-guide sitemap `lastmod`. `src/lib/site/guides.test.ts` enforces the invariants: a file per guide, the front matter matches, title at most 60 and description 110 to 160 characters, at least three sections, no checker issues on the GitHub, dev.to and Obsidian profiles, and every guide listed in `public/llms.txt`. To add a guide: write the Markdown with its front matter and add it to `llms.txt`; no code changes. When a guide changes, set `updated` to the new moment. - **Legal pages:** the Privacy Policy (`/privacy`) and Terms of Service (`/terms`) are `content/legal/.md` (no H1), with their title, description and date in `src/lib/site/legal.ts`, rendered like the guides and linked from the footer and the sitemap. `{{site}}`, `{{contact}}` and `{{repo}}` in the text are filled from `SITE` (`src/lib/site/seo.ts`, which holds the contact address). They describe what the product really does, so a change to what is stored or shared (a new provider, a new kind of data, analytics) must change them in the same pull request, and their date. diff --git a/docs/UI_SPEC.md b/docs/UI_SPEC.md index 6d6a12f..3d8f083 100644 --- a/docs/UI_SPEC.md +++ b/docs/UI_SPEC.md @@ -19,7 +19,7 @@ Text pages in the site layout (header, footer), in the same reading layout as a ## 1b. Guides `/guides` and `/guides/$slug` -Shared `SiteHeader` and `SiteFooter` (the footer has "mdstudio · version · MIT" on the left and Guides, Privacy, Terms and Changelog on the right). The index has a large "Markdown guides" heading and every guide as a tile (update date chip, title, description; the whole tile is the link). A guide page (`DocLayout`) has the "On this page" list in a sticky column on the left (from 1024px, hidden below, where the text is centred; the section being read is marked as the page scrolls), breadcrumbs, the title as the single `h1`, an "Updated … · N min read" line, the article (`.md-preview`), a call to action to open the editor on a tinted band, and three related guides as tiles. Unknown slugs return a real 404. The home page links to the first three guides. +Shared `SiteHeader` and `SiteFooter` (the footer has "mdstudio · version · MIT" on the left and Guides, Privacy, Terms and Changelog on the right). The index has a large "Markdown guides" heading and every guide as a tile (update date chip, title, description; the whole tile is the link). A guide page (`DocLayout`) has the "On this page" list in a sticky column on the left (from 1024px, hidden below, where the text is centred; the section being read is marked as the page scrolls), breadcrumbs, the title as the single `h1`, a "Published … · Updated … · N min read" line (each a `