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

Sign in to join this conversation.