Ledger Theme for GitHub Pages

Ledger is a documentation theme inspired by palmleafs and codex manuscripts. It is designed for clarity, readability, and zero-setup deployment on GitHub Pages, and is suitable for projects with a small set of doc files.

It supports Mermaid, static API pages, and interactive API pages.

Ledger has two presets, palmleaf (light) and night-ink (dark), with the option of overriding the presets with your preferences:

• Palmleaf, for the palmleaf look. Muted green with plant-ink brown text.
• Night Ink, for the codex-in-lamplight look. Deep brown with gold lettering.
• Custom, for your own colour choices.

On this page

• Enabling the theme
• Configuring the theme
• Setting up the sidebar ToC
• Logos and favicons
• Page elements
• API pages
  • Static API
  • Interactive API

Enabling the theme

1. In your own repository root, create a file named _config.yml with the following code snippet:

    remote_theme: AninditaBasu/ledger
    plugins:
      - jekyll-remote-theme
   

2. Enable GitHub Pages: In your repository settings, go to Pages > Deploy from branch > main.
3. Push your site files.

Your site should build itself with the palmleaf preset, which is the default. To use the dark theme (called night-ink), edit your _config.yml like so:

remote_theme: AninditaBasu/ledger
plugins:
  - jekyll-remote-theme
ledger:
  preset: night-ink

Configuring the theme

You can customise the ledger theme by specifying the following fields in your site _config.yml file.

Additionally, you can set the theme of any page to be different from the site theme, by specifying an override through the page front-matter, like this:

---
title: Dark Archive
ledger:
  preset: night-ink
  palette:
    accent: red
---

Customisation work by the following order of priority: Preset < Site config < Page frontmatter.

This means that the variables in the page frontmatter have the highest priority, followed by the values you specify through your _config.yml file. The default (and lowest priority) is the values specified in the two presets, which are palmleaf and night-ink.

Here’s an example snippet for _config.yml:

title: The title of your website
author: Your name
description: A human-friendly, SEO-friendly, RAG-friendly description.
github:
  repository_url: https://github.com/<your_github_name>/<your_repo_name>
remote_theme: AninditaBasu/ledger
plugins:
  - jekyll-remote-theme
ledger:
  preset: night-ink
  palette:
    accent: red

Setting up the sidebar ToC

Create a file called navigation.yml inside a _data folder in your project root (next to _config.yml). Then, specify the ToC in it. One level of nesting is supported.

For example:

- title: Home
  url: /
- title: Installing
  children:
    - title: Prerequisites
      url: /prereqs.html
    - title: Steps
      url: /install-steps.html
- title: Getting started
  url: /quick-start.html
- title: Configuring
  children:
    - title: Actions
      url: /config-action.html
    - title: Workflows
      url: /config-workflow.html

Logos and favicons

The logo goes on the sidebar and the favicon on the browser tab. Supported logo formats are PNG, SVG, WebP.

Place your images in an images folder in your project root; the theme automatically detects them.

images/
  logo.png
  favicon.ico
  favicon-16.png
  favicon-32.png

You can have your logo and favicon in more than one size, for example:

Page elements

Standard Markdown elements are supported.

Admonitions must be written like this:

{% include admonition.html
   type="warning"
   title="Warning"
   content="This one's a warning."
%}

The value for the type variable must be one of note, warning, tip, or caution.

API pages

API pages can be rendered directly from a JSON or YML file. Two kinds of rendering is available: static page and interactive page.

Static API

Create a folder called _data in your project root (next to _config.yml). Place the API specification file in this folder. The file can be in JSON or YML format.

Then, create a Markdown file with content similar to the following code snippet (which specifies, inter alia, that the layout file called api should be used):

---
layout: api
title: Title of the API
description: Description of the API
---

{% for ep in site.data.api.endpoints %}
## <span class="method">{{ ep.method }}</span> {{ ep.path }}
{{ ep.description }}
{% endfor %}

In this example, the _data folder contains a file called api.json, with the following structure, which is rendered as a static page:

{
  "endpoints": [
    {
      "method": "GET/PUT/etc.",
      "path": "/path_name",
      "description": "description"
    },
...
  ]
}

See static API example page.

Interactive API

Create a folder called assets in your project root (next to _config.yml). Place the API specification file in this folder. The file can be in JSON or YML format. Make sure that this specification file is written in the OpenAPI format.

Then, create a Markdown file with the following content (which specifies, inter alia, that the layout file called api-swagger should be used):

---
layout: api-swagger
title: Title of the API
openapi: /assets/name_of_your_api_spec_file.json
---

The rendered page is interactive. See interactive API example page.