A human- and AI-friendly GFM extension format for people who manage Markdown on GitHub
Gloss Markdown is an easy-to-use, highly readable extension format for GitHub Flavored Markdown (GFM). It is designed primarily for people who manage AI-written documentation on GitHub. The source remains readable as plain GFM, while dedicated Gloss Markdown tools can upgrade it into richer, easier-to-scan documentation.
Markdown is friendly to both humans and LLMs. HTML is powerful, but it is too much for README files and specs, and it does not fit well with GitHub-managed documentation. Gloss Markdown sits between GFM and HTML. It provides a small, predictable directive set that is just right for documentation managed on GitHub.
> [!WARNING] Production data
> This migration changes saved records.
````tabs
```tab title="CLI"
glmo docs/ --watch
```
```tab title="GitHub"
Install GlossView for GitHub chrome extension and open any `.gloss.md` file.
```
````
This API is `Stable`{badge color=green}. Press `Ctrl + S`{kbd} to save.GFM-compatible notation. Better readability. Fewer tokens.
- Rich documentation UI - Provides structured documentation elements such as callouts, details, tabs, cards, and badges.
- GFM-compatible -
.gloss.mdfiles are still readable as ordinary Markdown on GitHub, VS Code, terminals, and code review tools. - Small vocabulary - A simple specification with only callouts, details, cards, tabs, steps, grids, table of contents, badges, keyboard keys, and a few inline helpers.
- Consistent AI output - Fewer formatting choices reduce LLM output variance and help generate polished, unified documentation.
- Low token usage - Directives are compact Markdown patterns, not verbose HTML or JSX components.
- Safe rendering model - Gloss Markdown is data-only, so AI output can be rendered safely.
- Dedicated renderers - Use
GlossView for GitHub, a Chrome extension for GitHub, andglmo, a fork of k1LoW/mo, for local viewing.
AI-generated documentation usually falls into one of two shapes:
| Approach | Problem |
|---|---|
| Plain Markdown | Easy to edit, but limited in expressiveness, and long LLM-generated documents are not very scannable. |
| HTML | Rich, but too much for most documentation. It cannot be previewed naturally on GitHub, and its high freedom makes consistent formatting harder to maintain. |
Gloss Markdown adds a hidden gloss layer on top of GitHub Flavored Markdown. This layer is lightweight enough to avoid becoming noise during code review or fallback rendering, but structured enough for Gloss Markdown renderers to turn it into moderately rich, readable documentation UI such as tabs, callouts, grids, and badges.
Note
Gloss Markdown does not replace GitHub Flavored Markdown. It adds a small, safe vocabulary to GitHub Flavored Markdown.
Gloss Markdown files use the .gloss.md extension. They remain readable as ordinary Markdown on GitHub, VS Code, terminals, and code review tools even without a dedicated Gloss Markdown viewer.
Gloss Markdown supports all five GitHub Alert types.
> [!TIP] Component API
> Use this when documenting props, examples, and migration notes for a UI component.Supported types: NOTE TIP IMPORTANT WARNING CAUTION
Block directives use fenced code blocks.
```details title="Install"
npm install @acme/ui
```Standard block directives:
details card
Nested structures such as tabs and steps are expressed with a longer outer fence and normal inner fences.
````tabs
```tab title="TypeScript"
type ButtonProps = {
variant: "primary" | "secondary";
disabled?: boolean;
};
```
```tab title="JavaScript"
const props = {
variant: "primary",
disabled: false,
};
```
````Standard container pairs:
| Container | Child |
|---|---|
tabs |
tab |
steps |
step |
grid |
cell |
Void directives use an extended GitHub Alert form.
> [!toc title="Contents" depth=3]Standard void directives:
toc
Inline directives are written as an inline code span followed by an attribute block.
The Button API is `Stable`{badge color=green}.
Run `npm run dev`{kbd} to start the local server.Standard inline directives:
badge small big kbd heading
GitHub-flavored footnotes ([^id]) are also supported.
heading adds a background color to a heading without affecting any other behavior.
## `Button`{heading color=blue}
### `Props`{heading color=green}| Tool | Purpose |
|---|---|
| glmo | Local browser viewer for .md and .gloss.md files. It is explicitly a fork of k1LoW/mo, extended with Gloss Markdown rendering. |
| GlossView for GitHub | Chrome extension that renders Gloss Markdown directives on GitHub file pages. |