Add folio.md to your project, point it at your docs folder, and ship. Your repository stays focused on your content while folio.md handles the rest.

Install

folio.md isn’t yet published to npm. Install it directly from GitHub:

bun add github:amousavigourabi/folio.md       # bun
npm install github:amousavigourabi/folio.md   # npm
yarn add github:amousavigourabi/folio.md      # yarn

Scaffold

Run folio init from your project root:

bunx folio init    # bun
npx folio init     # npm / node
yarn dlx folio init  # yarn

This creates the following, skipping any that already exist:

1. folio.config.ts: your site configuration
2. docs/index.md: a starter welcome page
3. package.json scripts: folio:dev, folio:build, folio:preview, folio:check, folio:lint

Your configuration

The scaffolded folio.config.ts looks like this:

import { defineFolioConfig } from "folio-md/types";
 
export default defineFolioConfig({
  name: "My Docs",
  description: "Documentation for my project.",
  contentDir: "./docs",
  siteUrl: "https://docs.example.com",
});

contentDir is the path to your markdown files, relative to your repository root. You can point it anywhere: ./docs, ./content, ./wiki, etc. See Configuration for all available fields.

Develop

bun run folio:dev    # bun
npm run folio:dev    # npm
yarn folio:dev       # yarn

Opens a dev server at http://localhost:4321. folio.md picks up changes to your .md and .mdx files instantly.

Under the hood this runs astro dev inside the folio-md package directory, pointed at your folio.config.ts for all paths.

Add content

Drop .md or .mdx files into your contentDir. Every file becomes a page. Nested folders become collapsible sidebar sections. Each file needs at minimum a title in its frontmatter:

---
title: Getting Started
description: How to install and run the project.
---
 
Your content here.

See Writing Content for a full frontmatter reference, Mermaid diagrams, code blocks, and sidebar ordering.

Static assets

Put images, fonts, or other static files in a public/ folder at your repository root. They’re available at the root URL: public/logo.png is accessible at /logo.png.

Build

bun run folio:build    # bun
npm run folio:build    # npm
yarn folio:build       # yarn

Outputs a fully static site to dist/ in your repository root. The build validates all internal links and fails on broken links.

Preview the build

bun run folio:preview    # bun
npm run folio:preview    # npm
yarn folio:preview       # yarn

Serves the dist/ output locally so you can verify the production build before deploying. folio start is an alias for folio preview if you prefer the npm convention.

Type-check

bun run folio:check    # bun
npm run folio:check    # npm
yarn folio:check       # yarn

Runs astro check to type-check your MDX files and Astro components. Useful in CI to catch TypeScript errors without doing a full build.

Lint prose

bun run folio:lint    # bun
npm run folio:lint    # npm
yarn folio:lint       # yarn

Checks your content with Vale using the Vale and Google style sets. folio.md downloads both packages automatically on first run and caches them at ~/.folio-md/vale-styles/. Install Vale separately before running:

brew install vale          # macOS / Linux (Homebrew)
snap install vale          # Linux (Snap)
choco install vale         # Windows

Configure linting behavior in folio.config.ts. See Configuration for options.

Deploy

dist/ is a self-contained static site. Copy it to any host. For platform-specific instructions see Deployment.

When using GitHub Actions, check out with fetch-depth: 0 so folio.md can read git history for the “last updated” dates. Pick the setup step that matches your package manager:

- uses: actions/checkout@v4
  with:
    fetch-depth: 0
 
# bun
- uses: oven-sh/setup-bun@v2
- run: bun install
- run: bun run folio:build
 
# npm (Node.js is pre-installed on GitHub-hosted runners)
# - run: npm install
# - run: npm run folio:build
 
# yarn
# - run: yarn
# - run: yarn folio:build