nixpkgs/doc/contributing/contributing-to-documentation.chapter.md
Jan Tojnar 6ecc641d08
doc: prepare for commonmark
We are still using Pandoc’s Markdown parser, which differs from CommonMark spec slightly.

Notably:
- Line breaks in lists behave differently.
- Admonitions do not support the simpler syntax https://github.com/jgm/commonmark-hs/issues/75
- The auto_identifiers uses a different algorithm – I made the previous ones explicit.
- Languages (classes) of code blocks cannot contain whitespace so we have to use “pycon” alias instead of Python “console” as GitHub’s linguist

While at it, I also fixed the following issues:
- ShellSesssion was used
- Removed some pointless docbook tags.
2021-06-07 06:34:59 +02:00

3.6 KiB
Raw Blame History

Contributing to this documentation

The sources of the Nixpkgs manual are in the doc subdirectory of the Nixpkgs repository. The manual is still partially written in DocBook but it is progressively being converted to Markdown.

You can quickly check your edits with make:

$ cd /path/to/nixpkgs/doc
$ nix-shell
[nix-shell]$ make

If you experience problems, run make debug to help understand the docbook errors.

After making modifications to the manual, it's important to build it before committing. You can do that as follows:

$ cd /path/to/nixpkgs/doc
$ nix-shell
[nix-shell]$ make clean
[nix-shell]$ nix-build .

If the build succeeds, the manual will be in ./result/share/doc/nixpkgs/manual.html.

Syntax

As per RFC 0072, all new documentation content should be written in CommonMark Markdown dialect.

Additionally, the following syntax extensions are currently used:

  • []{#ssec-contributing-markup-anchors} Explicitly defined anchors on headings, to allow linking to sections. These should be always used, to ensure the anchors can be linked even when the heading text changes, and to prevent conflicts between automatically assigned identifiers.

    It uses the widely compatible header attributes syntax:

    ## Syntax {#sec-contributing-markup}
    
  • []{#ssec-contributing-markup-anchors-inline} Inline anchors, which allow linking arbitrary place in the text (e.g. individual list items, sentences…).

    They are defined using a hybrid of the link syntax with the attributes syntax known from headings, called bracketed spans:

    - []{#ssec-gnome-hooks-glib} `glib` setup hook will populate `GSETTINGS_SCHEMAS_PATH` and then `wrapGAppsHook` will prepend it to `XDG_DATA_DIRS`.
    
  • []{#ssec-contributing-markup-admonitions} Admonitions, set off from the text to bring attention to something.

    It uses pandocs fenced divs syntax:

    ::: {.warning}
    This is a warning
    :::
    

    which renders as

    ::: {.warning} This is a warning. :::

    The following are supported:

  • []{#ssec-contributing-markup-definition-lists} Definition lists, for defining a group of terms:

    pear
    :   green or yellow bulbous fruit
    
    watermelon
    :   green fruit with red flesh
    

    which renders as

    pear
    green or yellow bulbous fruit
    watermelon
    green fruit with red flesh

For contributing to the legacy parts, please see DocBook: The Definitive Guide or the DocBook rocks! primer.