A small, local GitHub for a directory of Markdown.
gh-mini # serve the current directory
gh-mini docs/ # serve another directory
gh-mini notes.md # serve the current directory and open notes.mdIt opens http://localhost:6419/ with:
- a file tree with a file finder (press
t), and directory pages that show their README, as GitHub does - Markdown rendered as GitHub renders it: alerts, task lists, footnotes, Mermaid, math, emoji
- source files highlighted, with line numbers you can link to
- HTML files previewed as a browser shows them, scripts included
- translations side by side, such as
guide.mdandguide.ja.md - themes, built in or written as CSS, each in light and dark
- what changed since the last commit, in the tree and as diffs, and on a branch, since it left the default branch
- live reload when files change
As a gh extension, run as gh mini:
gh extension install babarot/gh-miniOr with Go, run as gh-mini:
go install github.com/babarot/gh-mini@latestOr with Nix, run as gh-mini:
nix profile install github:babarot/nur-packages#gh-mini| Flag | Default | |
|---|---|---|
-p, --port |
6419 |
Port; the next free one is used when it is taken |
--host |
localhost |
Address to listen on |
--no-open |
Do not open the browser | |
--no-reload |
Do not reload pages when files change | |
--no-changes |
Do not read what changed since the last commit | |
--theme |
$GH_MINI_THEME |
Theme until one is picked in the settings |
--theme-dir |
~/.config/gh-mini/themes |
Directory of themes |
--preview-port |
a free one | Port HTML previews are served on, printed at start |
--skip |
.git,node_modules,.DS_Store |
Names left out of the tree |
--translations |
$GH_MINI_TRANSLATIONS, else suffix |
How translations are named |
--version |
Print the version |
How you like to see the pages, such as the theme, is picked in the settings in the page (press ,).
An HTML file's preview runs its scripts. They run in an origin of their own and cannot reach gh-mini's pages, but, as with python -m http.server, they can read the files gh-mini serves and send them anywhere. Preview only files you trust.
- Markdown: what is rendered as GitHub renders it, and which HTML is kept
- Files and live reload: what the tree shows, and what is watched
- Changes: what changed since the last commit, and where it shows
- Settings: the settings and keyboard shortcuts, and how they meet the flags
- HTML previews: how previews are served, and what their scripts can do
- Translations: how translations are named, and how to name yours otherwise
- Themes: writing a theme of your own
MIT