Skip to content
gh-docs

gh-docs CLI Reference

gh-docs is a GitHub CLI extension for assembling documentation indexes and generating starter site files.

Use case

Section titled “Use case”

It is a helper utility in the grand scheme of building consistent documentation for an entire GitHub or organization, utilizing GitHub Pages built-in sub page feature:

  • GitHub Pages parent/child feature
    A repository named {OWNER}.github.io (e.g. mindovermachine-dev.github.io) is a special repo. If it exists, it’s becomes the root of all other github pages under the user/organization — unless they explicitly define a different CNAME.
  • GitHub favors Jekyll
    GitHub has a special history with Jekyll. If a GitHub page does not use a GitHub Action to generate the static web site then it points to a branch/folder. That folder is expected to contain either valid HTML or a a valid Jekyll site which GitHub will then build and publish.
  • MarkDown is preferred
    GitHub pages only supports a small subset of Jekyll features and themes (see the github-pages gem). But the general concept that developers maintain their reference documentation in MarkDown only, and leave all boilerplate code aside is really a beautiful concept.
  • Remote Themes in Jekyll and Astro
    If you want to use a more verbose or feature rich jekyll theme or even a different static site generator like Hugo or Astro. Then you need quite a substantial amount of boilerplate code — It’s a scope creep. Now you’re not just maintaining content. Jekyll has an elegant solution; a jekyll-remote-theme gem which allows you to keep all your the boilerplate code for your website in a seperate theme repo and then continue to just keep the actual content files in your repo. The Astro Starlight theme has become the de facto standard for generating manual pages, but unfortunately Astro didn’t have an equivalent remote theme package so we built it. remote-asto-theme

Say you enable the GitHub pages for my-org/my-org.github.io and publish it on https://my-org.com (you set the CNAME). And then on a product repo in organization my-org/some-cli also setup GitHub pages, but leave the site field empty. Then it will automatically be published at https://my-org.com/some-cli