Introduction to Nudoc

This document is an introduction to the Nudoc hypertext format which powers the documentation for this blog.

Nudoc is a line-oriented format that allows you to define rich-text documents using a simple syntax. Nudoc is mainly inspired from Markdown, Gemtext and HTML.

Document header

Here's an example of a header:

Name: Introduction to Nudoc
Description: Learn the basics of the Nudoc markup format.
Slug: intro-to-nudoc
Date: 2024-12-10
---

Defining content

Line prefixes are used to define rich-content. Lines that don't start with any of the reserved prefixes are simply parsed as regular text.

Topics

Topics are used to title a section of content.

A topic is the second highest level of heading (like a HTML `<h2>`).

# Bananas

Note that the document's name is used like a HTML `<h1>` and meta `<title>`.

Links

> /fruits/banana Learn more about bananas!
> https://example.org Visit example.org

Which gets rendered as...

Links without labels are also supported for convenience.

> https://example.org

Which gets rendered as...

Lists

| My favorite fruits:
- Banana
- Apple
- Strawberry

Which gets rendered as...

Comments

If a line starts with "* ", consider the line to be a comment (until LF).

For example:

* TODO: Refactor.

Multiline comments and footnotes: if a line starts with "***", consider all next lines to be comments until "***" (or EOF) is encountered.

***
I'm a multiline comment.
I can span over multiple lines!
***

Note that inline comments are deliberately not supported.

Preformatted blocks and lines

A preformatted text block is simply text that is rendered "as is" in a monospace font. They are similar to HTML peformatted tags (`<pre>`) tag and Markdown triple backticks ` ``` `. There are useful for sharing code, ASCII art and much more.

Preformatted blocks are essential for software documentation because they mimic how text would be rendered in a code editor or CLI environment. Clients are also encouraged to make it easier for users to copy the preformatted content by for instance, providing a "copy to clipboard" button or prompt.

The syntax is the following:

``` bash
echo "Hello world!"
echo "Bonjour monde!"
``` Just some commands.

Which gets rendered as...

echo "Hello world!"
echo "Bonjour monde!"

In non-graphical environments, the client should provide to easily skip the preformatted block if it doesn't make sense to the client. Note that alternative content can be defined in a separate block type (see "Alternative blocks").

For convenience, when the preformatted content is a just a single-line-tall and you don't need metadata like the content type or legend, you may define it in a single line:

' echo "Hello world!"

Which gets rendered as...

echo "Hello world!"

Alternative blocks

Alternative blocks are meant to be presented to the user only in non-graphical environments.

You may use them after defining preformatted content that may not be easily understandable in a non-graphical context (ex: screen reader).

~ I'm alternative content.
~ I may spread over multiple lines.

Which gets rendered as...