[RFC 0072] Switch to CommonMark for documentation #72

mboes · 2020-07-13T11:18:43Z

This RFC proposes to convert the documentation for the Nix, Nixpkgs and NixOS projects from Docbook to CommonMark Markdown. It proposes requirements for the appearance of web facing documentation generated from Markdown. It does not mandate a choice of toolchain to generate a website with documentation. The choice is left to the implementers and maintainers.

rendered

This change is

This RFC proposes to convert the documentation for the Nix, Nixpkgs and NixOS projects from Docbook to CommonMark Markdown. It proposes requirements for web facing documentation. It does not mandate a choice of toolchain to generate a website with documentation. The choice is left to the implementers and maintainers.

rfcs/0000-commonmark-docs.md

Profpatsch · 2020-07-13T11:38:59Z

rfcs/0000-commonmark-docs.md

+1. good quality documentation search engine,
+1. syntax highlighting of all code,
+1. separate page per chapter, instead of the current monolithic page
+   for each manual,
+1. table of content for each chapter available in a side bar to easily
+   jump through long content,


The “good quality search engine” part becomes less of a problem when you put everything on one page, because the browser’s search bar is a tool that works everywhere, without internet connection.

Do we have too much documentation to fit everything on one page? Or what is the reasoning behind splitting it up?

That's a good point. The reasoning for the split-up is that this is what other projects with extensive documentation do as well. Presumably to make the documentation less intimidating (imagine coming to a project for the first time and realizing you're going to need to wade through 40k+ words of documentation...), but I'm not a tech writer so I'm not sure whether there are strong reasons.

Navigating from section to section currently isn't easy. But that can be solved with a sidebar TOC whether we're in single-page or multi-page.

I do think that the wall of text that are the current manuals is intimidating for first-time users. A collapsible TOC on the side would greatly help, plus it also degrades gracefully to the current experience when one has no JS.

I do think a one-page-man is more annoying (and resource-intentive) on mobile devices, though.

Emacsy projects usually have both split and unified manpages; that could be another option.

Our single page manual is no longer indexed by Google.

Reasoning of split-up is that google will rank one-page SEO farms quite low.

Additionally, URLs have to be search engine friendly so that random first-time Nix contributor blog is not ranked higher than the official documentation.

In which instances are the manuals not shown?

I assume if you search for content that exists in the manual, the results won't be found by google (or rated very low).

The “good quality search engine” part becomes less of a problem when you put everything on one page

I disagree. When I was new to Nix(OS) and I didn't know the terminology too well, I often had trouble finding things in the manual because I used too general terms (e.g. "build derivation") which resulted in a lot of unrelated results.

Also, on a search engine you can just combine terms that are relevant for the search, when performing a content-search in the manual using a browser you can't search e.g. for something like "nix rust derivation".

Don't get me wrong though, I really love the offline manual (including the PDF variants). Ideally, I'd love to see a split-up documentation on nixos.org and keep a single-page manual available offline (e.g. via nixos-help as it is currently the case).

In which instances are the manuals not shown?

I assume if you search for content that exists in the manual, the results won't be found by google (or rated very low).

I googled "declarative package management" and the nixpkgs manual is the 3rd result.

@grahamc @domenkozar is this a case of the ranking being too low? It seems like the page is definitely indexed though.

One problem with the one-page manual is that Google won't do proper deeplinking. Search for makeWrapper for example and it will send you to https://nixos.org/nixpkgs/manual/, no anchor applied.

This is less of a problem, when the pages itself are shorter and are more on topic for the search request.

The manual pages are also becoming more and more difficult to render on lower powered devices. It seems that throwing text on the screen using modern browsers is a hard task.

This, thus, reduces the accessibility of the manuals from users that don't have access to top tier machines like I figure a good chunk of Nixpkgs developers have.

While this is becoming less and less true in the developed world, bad internet that slows to a crawl is still a reality that exists. Splitting in distinct pages will also help accessibility in these instances.

domenkozar · 2020-07-13T11:40:26Z

rfcs/0000-commonmark-docs.md

+hegemony of RST in Python, because not all their users are Python
+programmers. They prefer not to count on writers learning Docbook or
+Asciidoc, because many documentation patches are from casual
+contributors. The *lingua franca* across subcommunities for both


That's exactly where the marketing and reality of Markdown differs. There are many standards of Markdown and most tooling implements their own format extensions, meaning you're not using Markdown but a flavor.

For that reason it's important to talk about the tooling used, as each documentation tool will use a different flavor and thus define the "vendor lock-in".

If not, does the RFC propose to ban extensions of the format?

That's why the title of this RFC has CommonMark in it, not Markdown. CommonMark is a well specified dialect of Markdown that is also a de facto standard (understood by GitHub, Sphinx, Gatsby, Pandoc and many others). We propose to use CommonMark for now: nothing added, nothing less.

That's quite nice in theory, but in practice the need for extensions quickly arises. My bet is we'll use one even as we port the existing documentation.

For example there are no footnotes, tables in CommonMark, what do you propose to do with the existing ones?

TOC is another example of such feature.

Only looking at the rust book, it's not just CommonMark as it uses extensions for includes: https://github.com/rust-lang/book/blob/master/src/ch18-03-pattern-syntax.md

Only looking at the rust book, it's not just CommonMark as it uses extensions for includes:

That's true. They use a preprocessor on top of Markdown. So do the projects I mention who use Hugo or Jekyll as their static site generator. These toolchains add special macros for includes. The Gatsby and React projects don't use that, and I believe we can get by just fine without a preprocessor given the current content.

Macros for textual includes could conceivably become useful down the road, but it will have little impact on users, who can still just write the CommonMark they know.

TOC is another example of such feature.

TOC's are a must in my book. I think we're in alignment there. Whether they need to be programmable from within the document markup is a different matter. The ReactJS documentation (and our demos) have TOC's auto-generated from the document structure. They are prominently displayed in the sidebar. Gatsby's documentation also has that. Although this is one other place where they use an MDX component: they go the extra mile and generate section specific "site maps" at the bottom of a few of their documentation pages.

I think CommonMark allows us to get most of the documentation writing done without many issues. In case one does touch upon its limits, things get harder, and one has to fallback to another language like e.g. HTML.

In my opinion this RFC should define what we fall back to. E.g., fallback to HTML, or, fallback to say reStructuredText? See e.g. how one can create a table with Sphinx + CommonMark:

```eval_rst +------------+------------+-----------+ | Header 1 | Header 2 | Header 3 | +============+============+===========+ | body row 1 | column 2 | column 3 | +------------+------------+-----------+ | body row 2 | Cells may span columns.| +------------+------------+-----------+ ```

Clearly this now becomes toolchain-dependent. In this case falling back to reStructuredText instead of HTML still allows the creation of pdf's.

As soon as you start using HTML, you lose portability of any kind (which may not be a requirement, but then we need to pick the tooling and commit to it).

That's true, but in practice:

HTML is seldom needed except for a few key things (tables and callouts),

different parts of the documentation are written for different media types.

The man pages are written for man. Tables in man pages are not a must have (and even if they were they are still supported by a number of man generation tools even if they were, like go-md2man, Pandoc and possibly Sphinx). Some users may be interested in PDF output rather than HTML output, but that's a matter of having decent CSS for the print media type. Likewise, I don't think EPUB support should be the deciding factor either, and we likely don't want to support that officially. But for those users who really want it Pandoc understands CommonMark (including HTML tables) as an input very well.

Clearly this now becomes toolchain-dependent. In this case falling back to reStructuredText instead of HTML still allows the creation of pdf's.

@FRidh what you're saying is that there exist corner cases, but those corner cases don't mean we're SOL - just that what happens then is not specified by any spec. I agree. AFAICS there are two or more tool choices available for all such corner cases (in particular tables) and all media types (in particular man pages). So long as this holds true, we're in a good place: it means we don't need to commit as part of this process to a specific implementation - just agree on the requirements for any such implementation, safe in the knowledge that satisfying the requirements won't be onerous.

There was enough bikeshedding in #64 that I'd rather make progress by agreeing on the format and the requirements for any toolchain, so that implementers don't have to spend heaps of time working towards a dead end because the community can't agree on the format (or indeed the requirements). (cc @domenkozar)

domenkozar · 2020-07-13T12:12:52Z

rfcs/0000-commonmark-docs.md

+format, which in any case *can* be extended with the wise use of
+`<span>`-like HTML tags and custom tags that expand to HTML. That
+appears to be seldom necessary in practice (see e.g. the five
+documentation examples in [Motivation][motivation]).


Drawback: no support for PDF, epub or manual pages.

We don't need PDF or epub. Manpages are apparently supported by Sphinx.

So the tooling matters here again, otherwise we will have to ditch services.nixosManual.showManual option.

Why? That option only requires an HTML rendering of the manual.

Ah right, I forgot that uses HTML instead of the manual page.

Co-authored-by: Profpatsch <mail@profpatsch.de>

rfcs/0000-commonmark-docs.md

Co-authored-by: Frederik Rietdijk <freddyrietdijk@fridh.nl>

abathur · 2020-07-13T15:27:19Z

I worry a little (both in #64 and here) that the natural order to make these decisions directs a lot of attention away from something that seems like one of the most-useful razors:

Across the ecosystem, what high-ROI tasks/work would people like to automate that will require access to some information in/from/about the docs? Will any given decision enable or impede doing so?

rfcs/0000-commonmark-docs.md

Co-authored-by: davidak <davidak@users.noreply.github.com>

samueldr · 2020-07-13T21:24:17Z

Is the form of the output in scope for this RFC? I am talking about the design, looks-wise, and also some of the function, which could be a magnet for bikeshedding.

If it isn't, it should be clearly stating it to prevent bikeshedding. I also propose that it states how the actual final form of the docs will be selected. (Another RFC? Collaboration between website team and docs team? Other proposal?)

If it is part of the discussion for this RFC, I think it will needlessly bog it down.

Now, the form of the output only lightly depends on the selected toolchain, in my experience. This RFC could (should?) still decide on a specific toolchain without ruling on the final looks and behaviour of the output.

I see that in Future work there is

Customize the CSS and layout of the demo to be more in line with Nix branding.

So I believe I am understanding right that the output looks and behaviour is not in scope of this RFC.

infinisil · 2020-07-13T23:47:35Z

In #64 we deemed some things as essential for a documentation format, one point of which was the ability to create references and being able to link to them from anywhere. This is very useful for option definitions being referenced in the manual, or by other options. Also very useful for link anchors.

As far as I can see, the CommonMark standard does not have any such thing. There's link references, but those don't work outside of the current document. So, if this RFC were accepted, we would not be able to ever have inter-document references. Is that correct?

If the answer is "Yes, but we can use this extension in $toolchain which can do this", then I reply with the fact that this then isn't CommonMark anymore, and we're then tied to $toolchain. So unless we can be sure that CommonMark has absolutely everything we will ever need, this RFC should instead be about choosing the tooling that can provide everything we need.

You also mention that

The motivation to switch to CommonMark is that among these projects, since roughly 10 times more projects use Markdown (or some variation thereof) than all other documentation formats combined, it can be considered the default.

How many of these projects are actually using spec-compliant CommonMark? Since you mentioned Markdown in that sentence, this let's me believe that most projects aren't using CommonMark, but rather CommonMark/Markdown + tooling-specific extensions, suggesting that pure CommonMark wasn't good enough for all of these projects.

So I really think we should include tooling in this decision, with all the extensions it provides that we might want to rely on.

michaelpj · 2020-07-14T09:08:04Z

I have to agree with @infinisil that the lack of proper inter-document cross-references is a deal-breaker.

I have also never worked on a project that used pure Markdown, there were always extensions because Markdown is just too minimal for any serious documentation project.

mboes · 2020-07-14T09:54:33Z

@samueldr

Is the form of the output in scope for this RFC? I am talking about the design, looks-wise, and also some of the function, which could be a magnet for bikeshedding.

Design: no. Function: yes. Quoting from the RFC:

The goal of this RFC is to change the form of the current documentation for Nix, Nixpkgs and NixOS to look similar to any one of the above 5 projects (see requirements in the next section).

In the "Detailed design" section, we list a number of requirements, which all have to do with what you call function above (but not design). While I really really want to avoid discussing implementation to avoid further bikeshedding, we should make sure that the choice of format doesn't paint us into a corner where important functionality would be impossible or hard to achieve. I listed a few requirements, but I may have overlooked some other important ones.

I believe that implementation should not be discussed as part of this RFC, for the following reasons:

There are a lot of factors to consider when choosing an implementation, including operational concerns and ease of maintenance. Choosing the implementation is an ill-formed question and bakes in endless potential for bikeshedding.
RFC's are a heavyweight process involving the entire community and require dozens of hours of work from the authors and the participants. Because of this, they have a strong normative power. We shouldn't have to go through the process all over again if the need arises to make big changes to the implementation (say as part of a revamp of the website).
Agreeing on requirements is one thing. But why should we involve the entire community on implementation choices that are mainly going to affect the livelihood of the authors (who will do the brunt of the initial work) and the maintainers (who will be saddled with the result for years to come)? I think we should defer implementation to a regular issue + PR process involving only authors and maintainers. This is both more efficient and more fair.
The choice of toolchain to generate the website does not affect users, or even documentation contributors. Beyond the choice of format, I submit that nothing here constitutes "a substantial change to the Nix ecosystem", as defined in the README for the RFC process. No changes to Nix itself. No restructuring of Nixpkgs. No new syntax in Nix-the-language.

I also propose that it states how the actual final form of the docs will be selected. (Another RFC? Collaboration between website team and docs team? Other proposal?)

Fair point. This is currently left implicit in the RFC as: whatever is the usual process for getting a change landed on the website (create an issue, open a PR, get it reviewed, merge). A collaboration between website and docs team (with external contributions) sounds like the right approach to me.

FRidh · 2020-07-14T09:54:37Z

Agreeing with the above I propose we extend the RFC stating we use Sphinx as tool, using the recommonmark plugin as CommonMark backend.

recommonmark has an ``````eval_rst ...``` for falling back to rst, allowing you to create tables and all other "more specific" things. Won't be needed for 95% of the docs but still adds significant values when it is needed;
recommonmark allows you to create relative links;
the community has many Python developers that have experience with Sphinx as well;
its plugin system and support for domains will be very valuable for us, e.g. so we can implement a Nix domain for describing functions.

(The gatsby mockup looks way nicer though, but I don't see any reason we could not achieve the same with Sphinx)

mboes · 2020-07-14T09:58:31Z

@michaelpj @infinisil

Folks say that there is no such thing as plain CommonMark, but fall short of stating what additional markup they believe is absolutely essential.

Furthermore, it would be good to back up any such claim with evidence. The RFC does include evidence to the contrary. As highlighted again in a previous comment, all 5 large projects cited in the RFC use plain CommonMark for markup except Kubernetes that uses one extension for tables and one for definition lists. Gatsby uses MDX to include newsletter signup forms, embed videos from third-party training websites, and build partial documentation sitemaps. Tools like Hugo, Jekyll and mdBook provide macros for textual file inclusion to what is regular CommonMarkdown.

Lastly, while this RFC does not propose to do so, what exactly would be so bad if we end up using one or two extensions here and there? Some extensions, like tables and definition lists, are already well supported by many documentation processing tools, as well as translation tools like Pandoc, and even if that weren't the case, translating the odd table or definition list by hand should we move to NewMarkupLangPro in the future takes far less time than this RFC discussion will likely take.

We could amend this RFC to require non-HTML tables. That would still not force a single implementation. Tables are supported by all of Gatsby, Hugo, Jekyll and mdBook, the toolchains used by the 5 projects cited in the RFC. Same goes for footnotes.

mboes · 2020-07-14T10:30:32Z

@FRidh thanks for pointing out that Sphinx supports these too, via eval_rst. So I guess that expands the set of possible implementations still further, even if the requirements were to be tightened to include a small number of CommonMark extensions. As I said above, I'm wary of discussing implementation options. Sphinx on the face of it looks like a perfectly fine contender, and indeed it is the basis of one of the demos cited in the RFC. I just had a comb through the GitHub Top 100 again. I may well have missed others, but I could find only one project that uses the Sphinx + recommonmark combo: Apple Swift (see here), who uses a mix of RST and Markdown files (newer files appear to be in Markdown). This is not a strong point either way - it just suggests that the pros and cons would have to be investigated further.

mboes · 2020-07-14T11:08:03Z

@infinisil

The motivation to switch to CommonMark is that among these projects, since roughly 10 times more projects use Markdown (or some variation thereof) than all other documentation formats combined, it can be considered the default.

How many of these projects are actually using spec-compliant CommonMark? Since you mentioned Markdown in that sentence, this let's me believe that most projects aren't using CommonMark, but rather CommonMark/Markdown + tooling-specific extensions, suggesting that pure CommonMark wasn't good enough for all of these projects.

I asked myself the same question and would love to know a good answer, but such an investigation ended up taking far too long. Focusing on just the 5 projects I cite in the RFC that are both in the Top 100 and also large and diverse projects (quite apart from their popularity), it appears that some (like React) use no extensions and no textual inclusion macros, Kubernetes uses 2 extensions (tables, definition lists) and macros, VSCode uses the table syntax from GFM but is otherwise plain CommonMark, and Gatsby uses a handful of custom MDX components, mostly to embed content.

mboes · 2020-07-14T11:42:11Z

@infinisil

As far as I can see, the CommonMark standard does not have any such thing. There's link references, but those don't work outside of the current document. So, if this RFC were accepted, we would not be able to ever have inter-document references. Is that correct?

I'm not sure what requirements you have in mind (if you write them out I can include them in the RFC), but what happens in practice is that cross-references are done with (root-)relative links and anchors. An example is the Gatsby project, which has extensive cross-referencing. Look at e.g. this page: https://www.gatsbyjs.org/docs/write-pages/. The sources (accessible using a button at the bottom) use a lot of links with anchors to entities defined elsewhere. It's up to the toolchain to check for dead links.

zimbatm · 2020-07-14T14:55:10Z

Since we did a few rounds of this documentation discussion already, we all know that the set that includes everybody's preferences is empty. At the same time, I think that we can all agree that any of the proposed formats are better than DocBook. In order to move forward, it will require some of you to let go of some of the technical details that are dear to you.

I support and would like to nominate myself as a shepherd if possible.

7c6f434c · 2020-07-14T15:10:31Z

I think that we can all agree that any of the proposed formats are better than DocBook.

Somehow I do not get the same impression from the discussion. It looks more like some of the people who wrote the most text for the manual have doubts whether any of the other formats are good enough, but consider Docbook acceptable. They might be willing to see whether the marketing team actually can organise a significant improvement of documentation if that specific thing changes, but this is not the same as agreeing that some format is definitely better. (As for me, last time I tried to write a bit of documentation, I failed to understand where in the current documentation it should even fit and gave up; I do not have any real opinion on these formats, although of course I like the clear escaping rules brought with XML, and dislike some of the error messages about wrong element nesting)

FRidh · 2020-07-14T16:04:58Z

Somehow I do not get the same impression from the discussion. It looks more like some of the people who wrote the most text for the manual have doubts whether any of the other formats are good enough, but consider Docbook acceptable.

Interesting, it is my impression that we generally agreed that, while technically all of the proposed formats are a step backwards, it is worth it for the overall project. And that at that point it also doesn't matter much which language/tool we pick considering the status quo.

It is therefore also my opinion that we should not investigate much further and just go ahead with any language/toolchain combo. Indeed CommonMark is a good fit, and as pointed out by @mboes there are different tools/extensions available for the other IMO important features such as tables and references. Then let's pick one and move on.

(As for me, last time I tried to write a bit of documentation, I failed to understand where in the current documentation it should even fit and gave up;

This is a far more interesting discussion that we ought to spend our time on, contents!

Let's be pragmatic here. Thus, to continue my previous post, would anyone be opposed to the Sphinx + CommonMark combo? If so, why?

jtojnar · 2020-07-14T17:08:03Z

I'm not sure what requirements you have in mind (if you write them out I can include them in the RFC), but what happens in practice is that cross-references are done with (root-)relative links and anchors.

Well, the problem is CommonMark spec does not have the notion of anchors. Some implementations add anchors to headings automatically, but implicit heading anchors

are limited to headings
- often, it makes sense to link to other elements, like a bullet point (example: https://nixos.org/nixpkgs/manual/#ssec-gnome-common-issues-unwrappable-package-gsettings-vala)
typically make the section address depend on the heading content
- so even minor changes break the anchor
  - and while you can check the references in-document, you will not be aware you are breaking external references
  - explicit anchors make it clearer there is a kind of a contract
  - maybe even better solution would be some kind DOI-like permalink database but until we have that, explicit anchors are reasonable compromise

So the requirement would be to be able to specify explicit anchors, both to sections (through headings) and to other types of content (paragraphs, list items, tables, code listings…).

There appears to be a CommonMark extension for that but, again, compostability is an issue. MDX might fare better.

davidak · 2020-07-14T17:11:07Z

Let's be pragmatic here. Thus, to continue my previous post, would anyone be opposed to the Sphinx + CommonMark combo? If so, why?

I think the syntax of Sphinx is not very user friendly. (but haven't used in a long time) So combining it with CommonMark seems not the best fit. That it is not popular in the top100 may be due to that.

So i would rather use one of the never, popular tools. Hugo is extremely popular in the space of static site generators and is actively developed. We can also use it for the website. We would be very flexible with it's huge ecosystem. (It supports interlinks https://gohugo.io/content-management/cross-references/ but has no native PDF export) (haven't used Gatsby, Jekyll or mdBook)

Mixing RST with Markdown might be confusing since they are very similar.

But i guess Sphinx is better suited for documentation and "Nix domain for describing functions" sounds great! So i would not opposed.

infinisil · 2020-07-14T17:18:04Z

To throw another possibility into the mix I'm very intrigued by: MyST

A fully-functional markdown flavor and parser for Sphinx.
MyST allows you to write Sphinx documentation entirely in markdown. MyST markdown provides a markdown equivalent of the reStructuredText syntax, meaning that you can do anything in MyST that you can do with reStructuredText. It is an attempt to have the best of both worlds: the flexibility and extensibility of Sphinx with the simplicity and readability of Markdown.

ryantm · 2020-10-31T02:26:48Z

The FCP is over. I'm not aware of any objections.

nh2 · 2020-10-31T17:15:54Z

rendered

@mboes The link in the issue description no longer works.

cole-h · 2020-10-31T17:17:17Z

Fixed rendered link: https://github.com/mboes/rfcs/blob/markdown-docs/rfcs/0072-commonmark-docs.md

AndersonTorres · 2020-11-01T05:10:38Z

My only concern here is:

Is there an Emacs mode for it? :)

FRidh · 2020-11-01T15:01:44Z

There is no link to the source for the example https://nixpkgs-manual-sphinx-markedown-example.netlify.app. View page source shows the intermediate reStructuredText. For NixOS/nixpkgs#102246 (comment) we would like to see the source.

zimbatm · 2020-11-04T08:34:40Z

Merging. Thanks all for your participation!

Mic92 · 2020-11-15T07:04:52Z

Since Nix uses mdbook now for documentation generation is this the plan for the other manuals as well?

worldofpeace · 2020-11-15T22:56:18Z

We made the decision during 20.09 management that the release process shouldn't be in the nixos manual. There should still be a section "NixOS Releases", but information that's useful to the user. Having the process there was really weird. It has since been split out to https://github.com/NixOS/release-wiki and I used mdbook with GitHub actions and pages.

samueldr · 2020-11-16T00:18:10Z

Since Nix uses mdbook now for documentation generation is this the plan for the other manuals as well?

It's a possibility. As part of next steps, we need to get the different interested parties together and talking about the tooling.

Part of interested parties are:

documentation people
website people

As previously stated, this is only about the input format; nothing the tooling.

FRidh · 2020-12-04T17:11:54Z

There is no link to the source for the example https://nixpkgs-manual-sphinx-markedown-example.netlify.app. View page source shows the intermediate reStructuredText. For NixOS/nixpkgs#102246 (comment) we would like to see the source.

I found a link in a comment. Do read the comment.

The README explains the history of that branch. It's based on @nlewo's earlier RST prototype prepared as part of #64, but with one file converted to Markdown.

So the example in this RFC was rst, not md...

asymmetric · 2020-12-06T08:17:24Z

Could someone with admin powers (or @mboes) fix the link in the PR description? :)

FRidh · 2020-12-06T08:25:22Z

Since Nix uses mdbook now for documentation generation is this the plan for the other manuals as well?

As far as I could discover mdbook lacks the possibility for the amount of nesting that is needed for Nixpkgs, which manual is significantly larger than the Nix one.

garbas · 2020-12-07T10:41:42Z

Since Nix uses mdbook now for documentation generation is this the plan for the other manuals as well?

As far as I could discover mdbook lacks the possibility for the amount of nesting that is needed for Nixpkgs, which manual is significantly larger than the Nix one.

Nesting (or folding as mdbook calls it) is configurable with [output.html.fold] -> https://rust-lang.github.io/mdBook/format/config.html. You can actually adjust the HTML output as you want, either by config, by template
or by writing extensions.

doronbehar · 2020-12-07T13:21:50Z

Nesting (or folding as mdbook calls it) is configurable with [output.html.fold] -> https://rust-lang.github.io/mdBook/format/config.html. You can actually adjust the HTML output as you want, either by config, by template
or by writing extensions.

Thanks for the link, I couldn't find it myself before. But it seems like it's related to the way the content is presented and it doesn't seem like there is or there isn't a restriction on the amount of levels of sections.

nixos-discourse · 2021-10-20T13:59:22Z

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/markdown-vs-asciidoctor/15583/3

NixOS/rfcs#72

roberth · 2022-05-31T10:47:26Z

Here's a migration plan for the module system descriptions, etc. NixOS/nixpkgs#175586

nixos-discourse · 2022-07-19T10:04:04Z

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/ideas-to-make-it-easier-to-contribute-to-the-documentation/20312/2

* Switch to CommonMark for documentation This RFC proposes to convert the documentation for the Nix, Nixpkgs and NixOS projects from Docbook to CommonMark Markdown. It proposes requirements for web facing documentation. It does not mandate a choice of toolchain to generate a website with documentation. The choice is left to the implementers and maintainers. * Update rfcs/0000-commonmark-docs.md Co-authored-by: Profpatsch <mail@profpatsch.de> * Update rfcs/0000-commonmark-docs.md Co-authored-by: Frederik Rietdijk <freddyrietdijk@fridh.nl> * Update rfcs/0000-commonmark-docs.md Co-authored-by: davidak <davidak@users.noreply.github.com> * Update rfcs/0000-commonmark-docs.md Co-authored-by: davidak <davidak@users.noreply.github.com> * Update rfcs/0000-commonmark-docs.md Co-authored-by: Ryan Mulligan <ryan@ryantm.com> * Add shepherd metadata * Add shepherd metadata * Allow CommonMark plus small number of extensions The exact set of extensions used is left to the documentation team. * Final adjustments - Nix now already uses markdown - Fix grammar mistake - Remove requirement of extensions having to be supported by at least 3 toolchains - Add requirement for an extension for references - Rename the file to its designated name Co-authored-by: Profpatsch <mail@profpatsch.de> Co-authored-by: Frederik Rietdijk <freddyrietdijk@fridh.nl> Co-authored-by: davidak <davidak@users.noreply.github.com> Co-authored-by: zimbatm <zimbatm@zimbatm.com> Co-authored-by: Ryan Mulligan <ryan@ryantm.com> Co-authored-by: Linus Heckemann <git@sphalerite.org> Co-authored-by: Silvan Mosberger <contact@infinisil.com>

asymmetric mentioned this pull request Jul 13, 2020

[RFC 0064] New Documentation Format for nixpkgs and NixOS #64

Closed

Profpatsch reviewed Jul 13, 2020

View reviewed changes

rfcs/0000-commonmark-docs.md Outdated Show resolved Hide resolved

Profpatsch reviewed Jul 13, 2020

View reviewed changes

domenkozar reviewed Jul 13, 2020

View reviewed changes

edolstra changed the title ~~Switch to CommonMark for documentation~~ [RFC 0072] Switch to CommonMark for documentation Jul 13, 2020

edolstra added the status: new label Jul 13, 2020

domenkozar reviewed Jul 13, 2020

View reviewed changes

Update rfcs/0000-commonmark-docs.md

df29e7f

Co-authored-by: Profpatsch <mail@profpatsch.de>

FRidh reviewed Jul 13, 2020

View reviewed changes

rfcs/0000-commonmark-docs.md Outdated Show resolved Hide resolved

Update rfcs/0000-commonmark-docs.md

323f6d9

Co-authored-by: Frederik Rietdijk <freddyrietdijk@fridh.nl>

davidak suggested changes Jul 13, 2020

View reviewed changes

rfcs/0000-commonmark-docs.md Outdated Show resolved Hide resolved

rfcs/0000-commonmark-docs.md Outdated Show resolved Hide resolved

mboes and others added 2 commits July 13, 2020 18:54

Update rfcs/0000-commonmark-docs.md

93dc997

Co-authored-by: davidak <davidak@users.noreply.github.com>

Update rfcs/0000-commonmark-docs.md

5c036a8

Co-authored-by: davidak <davidak@users.noreply.github.com>

nh2 mentioned this pull request Oct 31, 2020

doc: Explain how to link to options in the manual NixOS/nixpkgs#102246

Open

zimbatm merged commit 748cbd6 into NixOS:master Nov 4, 2020

Mic92 mentioned this pull request Nov 5, 2020

RFC meeting 2020-10-22 NixOS/rfc-steering-committee#48

Closed

13 tasks

lheckemann mentioned this pull request Nov 5, 2020

RFC meeting 2020-11-05 NixOS/rfc-steering-committee#49

Closed

13 tasks

jtojnar mentioned this pull request Dec 5, 2020

Harmonize docbook build experience NixOS/nixpkgs#68199

Closed

jtojnar mentioned this pull request Dec 14, 2020

nixos-manual: start gradual conversion to markdown NixOS/nixpkgs#106847

Closed

10 tasks

jtojnar mentioned this pull request Feb 22, 2021

doc: Port stdenv to Markdown NixOS/nixpkgs#113881

Merged

11 tasks

doronbehar mentioned this pull request Mar 28, 2021

undocumented: Mailspring requires gnome-keyring.enable = true; NixOS/nixpkgs#102637

Open

elikoga added a commit to elikoga/nixpkgs that referenced this pull request May 8, 2022

Update link from old nix manual to current stable one

04f6a43

NixOS/rfcs#72

elikoga mentioned this pull request May 8, 2022

Update link from old nix manual to current stable one NixOS/nixpkgs#172022

Merged

13 tasks

hsjobeki mentioned this pull request Jan 12, 2024

nixos-render-docs: cannot render commonmark NixOS/nixpkgs#280514

Open

hugosenari mentioned this pull request Feb 28, 2024

String type hint NixOS/nix#10099

Open

[RFC 0072] Switch to CommonMark for documentation #72

[RFC 0072] Switch to CommonMark for documentation #72

Conversation

mboes commented Jul 13, 2020 • edited by garbas

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

domenkozar Jul 13, 2020 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mweinelt Jul 13, 2020 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

domenkozar Jul 13, 2020 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

domenkozar Jul 13, 2020 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

abathur commented Jul 13, 2020

samueldr commented Jul 13, 2020

infinisil commented Jul 13, 2020

michaelpj commented Jul 14, 2020

mboes commented Jul 14, 2020 • edited

FRidh commented Jul 14, 2020 • edited

mboes commented Jul 14, 2020 • edited

mboes commented Jul 14, 2020

mboes commented Jul 14, 2020

mboes commented Jul 14, 2020

zimbatm commented Jul 14, 2020

7c6f434c commented Jul 14, 2020 via email

FRidh commented Jul 14, 2020

jtojnar commented Jul 14, 2020 • edited

davidak commented Jul 14, 2020

infinisil commented Jul 14, 2020

ryantm commented Oct 31, 2020

nh2 commented Oct 31, 2020

cole-h commented Oct 31, 2020

AndersonTorres commented Nov 1, 2020

FRidh commented Nov 1, 2020

zimbatm commented Nov 4, 2020

Mic92 commented Nov 15, 2020

worldofpeace commented Nov 15, 2020

samueldr commented Nov 16, 2020 • edited

FRidh commented Dec 4, 2020 • edited

asymmetric commented Dec 6, 2020

FRidh commented Dec 6, 2020

garbas commented Dec 7, 2020 • edited

doronbehar commented Dec 7, 2020

nixos-discourse commented Oct 20, 2021

roberth commented May 31, 2022

nixos-discourse commented Jul 19, 2022

mboes commented Jul 13, 2020 •

edited by garbas

domenkozar Jul 13, 2020 •

edited

mweinelt Jul 13, 2020 •

edited

domenkozar Jul 13, 2020 •

edited

domenkozar Jul 13, 2020 •

edited

mboes commented Jul 14, 2020 •

edited

FRidh commented Jul 14, 2020 •

edited

mboes commented Jul 14, 2020 •

edited

jtojnar commented Jul 14, 2020 •

edited

samueldr commented Nov 16, 2020 •

edited

FRidh commented Dec 4, 2020 •

edited

garbas commented Dec 7, 2020 •

edited