v0.19 documentation #1453

New issue

vyzo · 2026-06-08T17:07:34Z

vyzo commented

2026-06-08 17:07:34 +00:00

so no more js generated site -- npm is the biggest supply chain risk of modern times and i dont even install it in my computers.
But we do have a lot of docs and we want to preserve them -- in markdown.

So here is the proposal:

the docs are written in md with some select org mode syntactic facilities; we call that morg.
the docs live inside the src directory, next to the package or module they are documenting and their own directories for free standing docs
every package and module must have an accompanying morg document.
we will maintain existing documentation as much as possible, just rehome it.
it is appropriate to use LLM assistance for this.

Once we have enough docs ready, we will write a processor to render in html and other forms as appropriate.

Here is an example document outline for a package, say the std/io package living at src/std/io.md

# I/O Susbsystem
#+package

The `:std/io` package provides the implementation of the Gerbil I/O subsystem ...

## Examples
...

### Reading all the data from a Reader
#+example
...

## Exports

The package module reexports the symbols from [:std/io/api](io/api.md).

And here is the outline for a module documentation morg:

# Utilities for foo
#+module

this is what the foo module provides ...

## Exports
### bar
#+export

procedure to ...

...

so no more js generated site -- npm is the biggest supply chain risk of modern times and i dont even install it in my computers. But we do have a lot of docs and we want to preserve them -- in markdown. So here is the proposal: - the docs are written in md with some select org mode syntactic facilities; we call that morg. - the docs live inside the src directory, next to the package or module they are documenting and their own directories for free standing docs - every package and module must have an accompanying morg document. - we will maintain existing documentation as much as possible, just rehome it. - it is appropriate to use LLM assistance for this. Once we have enough docs ready, we will write a processor to render in html and other forms as appropriate. Here is an example document outline for a package, say the `std/io` package living at `src/std/io.md` ``` # I/O Susbsystem #+package The `:std/io` package provides the implementation of the Gerbil I/O subsystem ... ## Examples ... ### Reading all the data from a Reader #+example ... ## Exports The package module reexports the symbols from [:std/io/api](io/api.md). ``` And here is the outline for a module documentation morg: ``` # Utilities for foo #+module this is what the foo module provides ... ## Exports ### bar #+export procedure to ... ... ```

vyzo self-assigned this

2026-06-08 17:07:43 +00:00

fare was assigned by vyzo

2026-06-08 17:07:43 +00:00

HMarcien was assigned by vyzo

2026-06-08 17:07:43 +00:00

jay commented

2026-09-20 04:44:19 +00:00

@vyzo I've been thinking about the documentation markup language proposal . It seems like the main difference between markdown and your proposed "morg" is the ability to add attributes to headings (e.g. #+package). I looked around to see if there are any preexisting efforts in that vein, and I found a markup language called Djot. Djot was made by the same guy who made Pandoc and co-authored the Commonmark Markdown specification (so not a nobody), and it was designed to improve upon Markdown by improving parsing ambiguities and adding some really nice additional features .

Importantly, Djot allows for annotating arbitrary elements (both inline and block) with attributes. For example,

{package="std/io"}
# I/O Subsystem

I think there could be some benefit in leaning into an existing standard (even if it’s an uncommon one) rather than creating an entirely new one and contributing to the problem of xkcd:927. For instance, Djot already has a treesitter grammar, Emacs mode, VSCode extension, and many other DX niceties.

My thinking is we could build a parser in std/text/markup to parse Djot to an AST, and then we could built a tool that generates documentation-specific HTML using this parser and custom attributes like package, module, etc..

What are your thoughts?

@vyzo I've been thinking about the documentation markup language proposal . It seems like the main difference between markdown and your proposed "morg" is the ability to add attributes to headings (e.g. `#+package`). I looked around to see if there are any preexisting efforts in that vein, and I found a markup language called [Djot](https://djot.net/). Djot was made by the same guy who made Pandoc and co-authored the Commonmark Markdown specification (so not a nobody), and it was designed to improve upon Markdown by improving parsing ambiguities and adding some really nice additional features . Importantly, Djot allows for annotating arbitrary elements (both inline and block) with attributes. For example, ```md {package="std/io"} # I/O Subsystem ``` I think there could be some benefit in leaning into an existing standard (even if it’s an uncommon one) rather than creating an entirely new one and contributing to the problem of [xkcd:927](https://xkcd.com/927/). For instance, Djot already has a [treesitter grammar](https://codeberg.org/treeman/tree-sitter-djot), [Emacs mode](https://codeberg.org/crmsnbleyd/djot-mode), [VSCode extension](https://github.com/ryanabx/djot-vscode), and many other DX niceties. My thinking is we could build a parser in `std/text/markup` to parse Djot to an AST, and then we could built a tool that generates documentation-specific HTML using this parser and custom attributes like `package`, `module`, etc.. What are your thoughts?

🎉 1

vyzo commented

2026-09-20 07:27:10 +00:00

so i am not crazy for wanting annotations in my markdown 😄.
It looks good, let's use it. I would prefer if we kept the .md extension nonetheless.

so i am not crazy for wanting annotations in my markdown 😄. It looks good, let's use it. I would prefer if we kept the .md extension nonetheless.

vyzo commented

2026-09-20 07:27:54 +00:00

on the annotation side, let's annotate what we are documenting for the export symbols, eg procedure, struct, class, interface, macro, syntax, example

vyzo commented

2026-09-20 14:35:19 +00:00

another tag: we have tips in the existing documentation in the form of a vuepress extension:

::: [tip-type]
the tip
:::

we should turn those in appropriately nested subsections with a tip annotation.

another tag: we have tips in the existing documentation in the form of a vuepress extension: ``` ::: [tip-type] the tip ::: ``` we should turn those in appropriately nested subsections with a tip annotation.

Sign in to join this conversation.