redmine-kit/docs-skeleton

A VitePress skeleton that publishes the docs/ folder of a repository in the redmine-kit organization to GitHub Pages, at https://redmine-kit.github.io/<repo>/.

Every site gets the same header menu, listing the organization's plugins and projects, and the colors of Redmine. The repository redmine-kit.github.io is the organization's top site.

It is based on pieceofcake2/docs-skeleton, itself a fork of cakephp/docs-skeleton. The CakePHP branding, the book's navigation and analytics are removed; the header menu, the site list and the top page follow the same ideas.

This project is not affiliated with the Redmine project.

Add .github/workflows/docs.yml to the repository:

name: Docs

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  docs:
    if: github.repository_owner == 'redmine-kit'
    uses: redmine-kit/docs-skeleton/.github/workflows/repo-docs.yml@main

and set Settings » Pages » Source to GitHub Actions. The repository redmine-kit.github.io is the organization's top site and is published at https://redmine-kit.github.io/; link from it to the other sites with <a href="/<repo>/" target="_self">, so that the browser loads them instead of this site's router. The reusable workflow .github/workflows/repo-docs.yml builds the site with config.repo.js and deploys it. It deploys only from the default branch of a repository in the organization.

• Rebuilding: the site is rebuilt only when docs/ changes. After changing something else that the site shows (the workflow, the repository description, LICENSE), or after a change to this skeleton, run the workflow by hand from the Actions tab (Run workflow).

• Inputs: title sets the site title, prepare a shell command that runs in the repository's checkout before its docs/ is copied (to add pages made from other files of the repository, see Generated pages), and skeleton-ref the branch, tag or SHA of this skeleton to build with (default: main). To pin the skeleton, pass the same ref to both:

  jobs:
    docs:
      if: github.repository_owner == 'redmine-kit'
      uses: redmine-kit/docs-skeleton/.github/workflows/repo-docs.yml@<sha>
      with:
        skeleton-ref: <sha>
        title: My Theme

The site needs no configuration in the repository:

• Home page: docs/README.md. Other Markdown files in docs/ are further pages (docs/foo/README.md is served as foo/).
• Title: the workflow's title input, or title in the front matter of docs/README.md, or its first # heading. The Japanese site uses those of docs/ja/README.md.
• Description: the repository's description, or Documentation of owner/repo when it has none.
• Sidebar: the pages and their ## headings. The home page comes first, then the pages in the order docs/README.md links them, then the other pages by path. A page's title is its # heading (or title in its front matter).
• Links: link pages by their Markdown file, for example [Installation](installation.md#docker); the site turns them into links to its pages. Links to other files and out of docs/ (for example ../LICENSE) point to the file on GitHub, so the Markdown works both on GitHub and on the site.
• Anchors: heading anchors are the same as on GitHub. A link to a heading that moved to another page is forwarded to that page.
• Images: images in docs/ (for example docs/img/) are bundled. Images must be inside docs/: an image outside it (../screenshot.png) stops the build.
• Checked links: links between pages and to their headings are checked when the site is built, and a broken one stops the build.
• Vue: {{ ... }} in text, inline code and code blocks is shown as text, not evaluated. Inside raw HTML it is still evaluated by Vue.
• Code blocks: an indented code block looks like a fenced one, as a block of text.
• Callouts: ::: tip containers and GitHub's alerts (> [!NOTE], also with a title: > [!WARNING] Title) are titled as Redmine titles its alerts, in English and in Japanese (注記, ヒント, 重要, 警告, 注意).
• Localhost: links to localhost (a local server in examples) are not checked.

A repository whose site shows more than docs/ (for example content kept in other folders) adds those pages with the prepare input. The command writes them into docs/ of the checkout before the build:

jobs:
  docs:
    if: github.repository_owner == 'redmine-kit'
    uses: redmine-kit/docs-skeleton/.github/workflows/repo-docs.yml@main
    with:
      prepare: ruby tools/site.rb docs

• Sidebar: docs/sidebar.json (and docs/ja/sidebar.json), in VitePress's sidebar format, replaces the generated sidebar of that language. Links to a heading that moved to another page are then not forwarded.
• Edit and source links: a generated page is not a file of docs/ on GitHub; editLink: false in its front matter hides both its "Edit this page" link and its source link.
• Anchors: a heading can set its anchor with {#anchor} (## Heading {#anchor}); the Markdown version of the page leaves it out.
• Images: a generated page can show images from docs/public/ with absolute paths (/images/screen.png).
• Rebuilding: add the folders the command reads to the paths of the workflow's push trigger.

Put the Japanese pages in docs/ja/, with the same file names as the English pages. When docs/ja/README.md exists, the site gets a Japanese version at /<repo>/ja/, with a language switcher, its own sidebar and Japanese labels. Links from docs/ja/ to files of the repository go one level further up, for example ../../LICENSE.

Japanese headings have other anchors than the English ones. Put the English anchor before each Japanese heading, so that links work in both languages (links to a moved section are forwarded for these anchors too):

<a id="installation"></a>

## インストール

The header menu of every site is built from .vitepress/sites.js, which lists the organization's repositories in groups:

{
  id: 'plugins',
  en: 'Plugins',
  ja: 'プラグイン',
  items: [
    {
      repo: 'redmine_lookbook',        // repository name, and the path of its site
      name: 'Redmine Lookbook',        // display name
      status: 'design',                // optional: 'design' or 'consideration'
      en: 'Previews ...',              // one-sentence description
      ja: '...',                       // Japanese description
      // docs: false,                  // the repository has no documentation site
    },
  ],
}

• Menu: "Home" (the top site), then one dropdown per group (Plugins, Projects). The entry of the current site is highlighted and links within the site; the others open the other sites in the same tab. A repository with docs: false links to GitHub.
• Top site: the same list is shown as cards on the top site (see below).
• Adding a repository: add it to sites.js once its site is published, then run the docs workflow of every site by hand (Actions » Docs » Run workflow), so that all menus include it.

The repository redmine-kit.github.io is published at https://redmine-kit.github.io/ (its site has the base / instead of /<repo>/). Its docs/README.md is a VitePress home page:

---
layout: home
title: Redmine Kit
hero:
  name: Redmine Kit
  text: Open-source tools for Redmine
  actions:
    - theme: brand
      text: Plugins
      link: '#plugins'
---

## Plugins

<SiteList group="plugins" lang="en" />

• <SiteList group="..." lang="en" /> shows the repositories of a group of sites.js as cards, with links to the documentation, its Markdown (llms.txt) and GitHub. In the Markdown version of the page and in llms.txt, it becomes a Markdown list.
• Links from the top site to the other sites use <a href="/<repo>/" target="_self">, so that the browser loads them instead of this site's router.
• In the repository settings, Pages » Source must be GitHub Actions. GitHub may turn on its own Jekyll build for <owner>.github.io repositories; it then replaces this site with the README on every push.

• Colors: the red of Redmine's logo (#C70201) for the accent and the buttons, a deep red header bar (#7F0000 in dark mode) with white text, and links in a darker red. Menus that open from the header keep the normal colors.
• Japanese: the Japanese locale gets Japanese labels, including the search box. Japanese headings and the top page's hero break between phrases (BudouX), not between any two characters; body text keeps the browser's line breaking.
• Icons and link previews: docs/public/ holds the favicon and the image of link previews (og-image.png), made from the Redmine Kit logo (in the private repository redmine-kit/brand). Every page gets Open Graph and Twitter card tags with its title, description and URL. A file of the same name in a repository's docs/public/ replaces the skeleton's.

The search box searches every redmine-kit site, with Pagefind. npm run docs:build writes the site's index to pagefind/ in the built site (pagefind.yml); the search on any site uses its own index and merges the indexes of the other sites in sites.js, ranked below its own. Each result shows the name of its site. Only the content of the pages is indexed, not the header, sidebar and footer. A site whose index does not load (not published yet, or built with another Pagefind version) is left out of the search. docs:dev builds no index, so the search finds nothing there; use docs:build and docs:preview.

Every page is also published as Markdown next to its .html (/<repo>/installation.md), with llms.txt and llms-full.txt for each language (llms.txt). Every page links its Markdown in its head and its footer. A page with llms: false in its front matter is left out.

npm ci
rsync -a --delete ../redmine_lookbook/docs/ docs/
cp config.repo.js config.js
export DOCS_REPOSITORY=redmine-kit/redmine_lookbook
npm run docs:build
npm run docs:preview

docs:preview reads the configuration too, so it needs the same variables.

.npmrc sets ignore-scripts=true, so the install scripts of dependencies do not run.

.
├── .vitepress/
│   ├── config.js          # Default VitePress configuration
│   ├── markdown-output.js # Markdown of the pages, llms.txt (buildEnd)
│   ├── sites.js           # The organization's repositories (header menu, top site)
│   ├── site-nav.js        # The header menu built from sites.js
│   ├── utils.js
│   ├── plugins/           # markdown-it plugins (links to GitHub, substitutions)
│   └── theme/             # Theme: colors, site cards, Markdown links, moved anchors
├── config.repo.js         # Configuration for a repository's site
└── docs/                  # The repository's docs/, copied in by the workflow
    └── public/            # Favicon and link preview image of every site

npm run lint

redmine-kit/docs-skeleton is released under the MIT License. See LICENSE. An unofficial project for Redmine.