folder2website

Build a static site from a repo or markdown folder.

• Starts at README.md.
• Follows local markdown links recursively.
• Copies referenced assets.
• Writes HTML and markdown twins to site/.
• No frontmatter.

Run#

bunx github:spashii/folder2website#main owner/repo
bunx github:spashii/folder2website#main . --serve
bunx github:spashii/folder2website#main . --serve --port 4322
bunx github:spashii/folder2website#main . --base-url https://example.com
bunx github:spashii/folder2website#main . --manifest docs/site.webmanifest
bunx github:spashii/folder2website#main . --hide-generator-attribution
bunx github:spashii/folder2website#main . --hide-footer-actions

Private repo:

GITHUB_TOKEN=github_pat_... bunx github:spashii/folder2website#main owner/repo

Options#

• --out <dir>: output directory. Default: site.
• --entry <file>: seed page. Repeatable. Default: README.md.
• --base-url <url>: production URL for canonical tags, sitemap, robots and OG. Also makes the links in llms.txt absolute.
• --manifest <path>: manifest path. Relative paths resolve from the target repo. Default: manifest.json.
• --clone-dir <dir>: exact clone destination for a remote repo. Existing clones are reused as-is.
• --hide-generator-attribution: omit the folder2website attribution from page footers.
• --hide-footer-actions: omit the edit and copy actions from page footers.
• --hide-commit-info: omit the Created and Updated lines, which come from the git log of each page.
• --hide-related-pages: omit the generated related-page list. Markdown links still populate the knowledge graph.
• --serve: live preview.
• --port <n>: live preview port. Default: 4321.

Output#

• README.md becomes index.html.
• Linked local .md files become .html pages.
• Extensionless local text links like LICENSE become pages.
• A markdown twin is written next to every page, such as index.md or guide.md.
• Referenced assets are copied.
• llms.txt in the llmstxt.org format: site title, summary, then the markdown twins listed per top-level folder. Translations go under Optional. Links are relative unless --base-url is set.
• llms-full.txt: every default-locale page inline, each under its title with a Source: line.
• Every page links its twin with <link rel="alternate" type="text/markdown">.
• With --base-url, the output includes sitemap.xml and robots.txt.

Rendering#

• Shiki syntax highlighting.
• Mermaid diagrams. Mermaid fences render in the browser in the site’s own colours and font, follow light and dark, spill past the reading column like tables, and open full size on click. A fence that fails to parse shows its source and the error. The library ships only when a page uses one.
• GitHub alerts.
• Footnotes.
• Heading anchors.
• Table of contents.
• Standalone text links rendered as action buttons. Links inside sentences stay inline.
• Tables spill past the reading column, centred, up to 1040px, and scroll only when wider than the viewport.
• Copy-code buttons.
• Image lightbox.
• Hover previews for internal pages.
• Git footer with an edit link, Markdown copy action, authors, and generator link.
• Manifest-based title, description, icon, colors, and optional extra CSS. @import rules in the extra CSS (web fonts) are hoisted to the top of the stylesheet so they take effect.

Navigate & explore#

• Breadcrumbs from the link graph, collapsing the middle when deep.
• Light/dark theme that follows the OS, with an alternate dark logo.
• Site search from a top-right icon, built on MiniSearch. Results support keyboard navigation and links to matching sections. The output includes the index as search-index.json.
• Knowledge graph from a top-right icon, built on d3-force. Pages keep one stable layout. Selecting a page highlights its links without rearranging the graph. The detail rail lists links and backlinks. Backlink emphasis is off by default. Graph colors and type use roles from the manifest theme.
• A grouped “Related pages” list on each page. It can open the graph focused on the current page. Use --hide-related-pages when the source already has its own related-links section.
• Optional language switcher. See docs/manifest.md.
• Optional giscus comments. See docs/manifest.md.

d3-force and MiniSearch are vendored under vendor/ (see vendor/README.md) and copied into the output, so a built site needs no third-party scripts at runtime.

Deploy#

GitHub Pages recipe: docs/deploy-with-github-pages.md.

Manifest mapping: docs/manifest.md.