x386.org

PageSprig

Markdown in, a website out.

Write your documents in Markdown. Define the menu in YAML. Run a small Python program and get a static website.

PageSprig is built for documentation, practical guides, and personal reference sites. It keeps the writing and publishing process simple, while providing the navigation and reading layout a useful site needs.

Get PageSprig · Read the documentation

Simple, but not stupid

PageSprig started with a straightforward need: turn a collection of Markdown files into a readable website without maintaining a large website framework.

The approach is deliberately small. Your content stays in ordinary files, your navigation is explicit, and the output is HTML, CSS, JavaScript, and media files you can host yourself.

Markdown, YAML, and HTML templates are handled by established libraries. The generator uses Python; the finished website does not need it.

What you get

  • A menu you control. Define group names, page labels, and ordering in config.yaml. Your folder structure does not dictate the menu.
  • A comfortable reading layout. Responsive navigation, a page contents list, and light/dark themes.
  • Five accent colors. Choose blue, green, amber, purple, or rose.
  • Navigation that remembers. Expanded menu groups and sidebar scroll position survive page changes.
  • Useful code blocks. Copy buttons and optional language labels, with plain, readable code.
  • Optional sequential reading. Enable previous/next links for a tutorial or a series of lessons.
  • Customizable text. Set copy, pagination, theme, and page contents labels to suit your site's language.

The home page shares the site layout and stays out of the menu. Its visible content comes entirely from your Markdown.

Get started

You need Python 3.10 or newer, with support for venv and pip.

git clone https://git.disroot.org/Enatsek/pagesprig.git
cd pagesprig
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
cp -r example/content content
.venv/bin/python pagesprig.py

Open site/index.html in your browser. Edit your Markdown and run the generator again when you want to update the site.

To publish, upload the contents of site/ to your web host. The generated site requires no application server, CDN, or external fonts.

Your files, your structure

A small site might look like this:

content/
  config.yaml
  index.md
  guides/
    installation.md
    configuration.md

The menu is just as straightforward:

site:
  title: My Documentation
  accent: green
  pagination: false

menu:
  - title: Getting Started
    pages:
      - title: Installation
        file: guides/installation.md
      - title: Configuration
        file: guides/configuration.md

Write page headings in Markdown. Use optional frontmatter for browser-tab titles and descriptions. Markdown links between documents become links between the generated HTML pages.

Complete configuration example

This example includes every supported config.yaml setting. Paths are relative to your content directory; the referenced pages must exist. The optional logo line is commented out so you can enable it after adding an image.

site:
  # Required: header title and part of browser-tab titles.
  title: My Documentation
  # Optional: defaults to images/logo.svg, .png, .webp, then .jpg.
  # If no logo exists, only the site title is shown.
  # logo: images/logo.svg
  # HTML language code; does not automatically translate labels.
  language: en
  # blue (default), green, amber, purple, or rose.
  accent: blue
  # Previous/next links in menu order; default: false.
  pagination: false

code:
  # Show the language specified on fenced code blocks; default: true.
  # Set to false to hide labels while keeping copy buttons.
  show_language: true

# All labels are optional. These are the English defaults.
labels:
  copy: Copy
  copied: Copied!
  # Appears only when automatic copying fails.
  copy_hint: Code selected. Press Ctrl+C or Command+C to copy.
  # Pagination arrows are added automatically.
  previous: Previous
  next: Next
  on_this_page: On this page
  # Name the theme to switch to, rather than the current theme.
  dark: Dark
  light: Light

# Groups and pages appear in the order written here.
# Page titles are menu labels; file paths identify the Markdown documents.
menu:
  - title: Getting Started
    pages:
      - title: Installation
        file: guides/installation.md
      - title: Configuration
        file: guides/configuration.md

  - title: Guides
    pages:
      - title: Writing Documents
        file: guides/writing.md
      - title: Publishing Your Site
        file: guides/publishing.md

  - title: Reference
    pages:
      - title: Configuration Options
        file: reference/options.md
      - title: Frequently Asked Questions
        file: reference/faq.md

Each top-level title creates a separate collapsible menu group. This example has Getting Started, Guides, and Reference; their file paths do not need to match the group names.

For a single-page website, replace the entire menu section with menu: []. PageSprig then omits the sidebar and centers the content. The home page is always index.md and must not be listed in the menu.

Change only the labels you need; omitted values retain their English defaults. Other controls, such as the mobile Menu button, remain English. Use pagination: true for ordered lessons, or leave it off for independent documents.

Keep it yours

Use PageSprig for your own notes, a collection of independent guides, or an ordered set of lessons. Change the colors through configuration, or edit the HTML template and CSS when you need a different layout.

PageSprig is free software, licensed under GPL-3.0-only.

Browse the source and documentation

x386.org