MARK IT DOWN
Mark It Down
الصفحات · Mark It Down

Publish to GitHub Pages

Status: shipped in Phase 0.10 · Issue: #11 · Depends on: #10 Notes warehouse

Publish your global notes (or any markdown file) as a public static site hosted on GitHub Pages. Builds a self-contained HTML site with the same Mark It Down rendering pipeline (marked + highlight.js + mermaid + sortable tables) and pushes to the warehouse repo's publish branch (default gh-pages).

At a glance

WhereCommand palette → Mark It Down: Publish: … (4 commands)
SourceAll global notes (Deploy Site) or just the active markdown (Deploy Current Page)
TargetThe warehouse repo (markItDown.warehouse.repo) on the gh-pages branch (configurable) under markItDown.publish.path (configurable)
Enginemarked → HTML, highlight.js for syntax tokens (server-side), mermaid loaded from a CDN at view time
ThemeAny of the 25 bundled palettes baked into assets/style.css
OutputOne HTML page per source file + index.html listing all pages + shared assets/style.css and assets/site.js

Commands

CommandWhat it does
markItDown.publish.deployPublish all global notes as a full site rebuild. Wipes the publish branch's working tree, regenerates everything, commits + pushes.
markItDown.publish.deployCurrentPublish only the markdown in the active editor as <basename>.html at the publish root. Useful for one-off shares.
markItDown.publish.copyUrlCopy the public URL for the active markdown file to the clipboard. Doesn't trigger a build.
markItDown.publish.openSiteOpen the deployed site in your default browser.

Settings

SettingDefaultWhat it does
markItDown.publish.enabledfalseMaster switch. Must be true for any deploy to run.
markItDown.publish.branch"gh-pages"Branch on the warehouse repo to push to. Created as an orphan branch on first deploy if it doesn't exist remotely.
markItDown.publish.path"" (root)Subdirectory under the publish branch root to write the site into. Useful if the same branch hosts multiple sites.
markItDown.publish.includeGlob"**/*.md"Glob filter for source files in Deploy Site. (v1 only filters by extension; full glob matching is a future addition.)
markItDown.publish.theme"github-light"Which of the 25 bundled palettes to bake into the published site's CSS.

Quick start

jsonc

Then:

  1. Make sure GitHub Pages is enabled for the warehouse repo (Settings → Pages → Source: deploy from branch → branch gh-pages → folder /).
  2. Run Mark It Down: Publish: Deploy Site from the command palette.
  3. Open the URL it prints — typically https://<owner>.github.io/<repo>/ (plus your path subdir if configured).

How it works

text

The publish flow uses git worktree to keep the orphan publish branch in a separate working directory under globalStorage/publish/<repo-slug>/. That way the warehouse working clone (used by F9 for sync) and the publish branch don't fight over the same checkout. The worktree is removed after each push so subsequent deploys start fresh.

Output structure

For two notes, "Sprint 12 retro" and "Postgres tuning":

text

Each HTML page is self-contained: relative links to the shared assets, no JS frameworks, no inline <script>. Mermaid is loaded from https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js only when a page actually contains a .mermaid element.

Pages layout

Every published page has:

  • Header — link back to index.html ("Mark It Down" home) + the page title
  • Sidebar nav — the same list of all pages, with relative links so it works at any deploy depth
  • Body — the rendered markdown
  • Footer (none) — the layout is intentionally minimal so the content is the focus
  • Responsive: under 720px wide, the sidebar collapses

Sortable tables in the public site

Tables in published pages are sortable: click any column header to cycle asc → desc → none. The behavior matches the in-VSCode DataTable feature — same parsing logic (numeric strip + localeCompare). Implemented in assets/site.js with vanilla JS, no framework.

Mermaid in the public site

Mermaid blocks are rendered client-side — assets/site.js lazy-loads mermaid from JSDelivr only when the page contains at least one .mermaid div. Theme follows the published-site theme's kind (light/dark) at load time.

What's not in v1

Tracked as future-work seeds in the issue body and this docs page:

  • First-run wizard — verify the warehouse repo is public, verify Pages is enabled, offer to flip both via gh api. v1 just deploys; if Pages isn't enabled, the URL won't resolve until you flip it manually.
  • Privacy guard for private repos — v1 doesn't warn before publishing to a private repo. The site will be 404 until the repo is public; no leak risk, but a clearer message would be friendlier.
  • Per-folder includeGlob filtering — v1 publishes all global notes regardless of includeGlob. Glob matching is wired in settings but not yet applied.
  • Per-page slug overrides — files are named <slug>-<id>.html from the note title. Stable across renames (because of the id suffix) but ugly. A frontmatter slug: override is a future addition.
  • Embedded images — markdown image references aren't rewritten to local paths or copied. They render via the original URL (which works for hosted images). Local relative-path images would need a copy pass.
  • Sitemap / RSS — would be ~30 LOC to add.

Edge cases

  • Warehouse not configured: Publish commands surface an info toast pointing to settings. No deploy attempted.
  • Publish disabled (enabled: false): Deploy Site and Deploy Current show a warning + "Open Settings" action. Copy URL and Open Site still work (they don't deploy).
  • First deploy (no gh-pages branch yet): the publisher creates an orphan branch via git worktree add -B, wipes any inherited tree, writes the site, commits + pushes. Subsequent deploys reuse that branch.
  • Push fails (e.g. credential issue, branch protection): error toast surfaces the git stderr; the worktree is cleaned up regardless.
  • No notes to publish: Deploy Site shows "nothing to publish" and exits.
  • Active editor isn't markdown: Deploy Current Page reads whatever the active editor's URI points at, treating it as markdown. Non-markdown content goes through marked anyway and renders as plain paragraphs; not great UX but not destructive.
  • Theme auto: not valid for publish. Default github-light is used if you set auto here.

Files of interest