Support of Markdown

[villanella]

We want to edit documents with markdown syntax, and export sdoc to markdown for the integration with task tracker system.

[stanislaw]

Hi @villanella, thanks for asking! The markdown support is on the roadmap, but it is of lower priority and is not something that can be done very quickly, especially if you want to use the web interface and not just edit the text files and get the static HTML export.

StrictDoc already supports the MARKUP option per-document:

[DOCUMENT]
TITLE: Hello world doc
OPTIONS:
  MARKUP: HTML

This option could be extended to also include Markdown, which would make the HTML and other exports recognize that we are dealing with Markdown, not RST or other formats.

Also, the RSTWriter class could be cloned to MarkdownWriter and adjusted to the specifics of the Markdown format. A good and fast Markdown renderer has to be found somewhere on GitHub as a Pip package. For RST, the docutils library is used as the most representative for RST. Something similar has to be found for Markdown.

Finally, the static HTML export and the web interface functions have to be adjusted to be not hard-coded to RST but also support Markdown.

All these things are definitely doable, but there are work items of higher priority for me and @mettta right now.

If you have spare time to contribute this feature yourself, I could provide pointers on how this could be done but get ready to allocate one or two months of open source work to get this done, depending on whether you have existing Python experience.

[villanella]

Thank you @stanislaw for development recommendations!

[stanislaw]

For anyone landing here, please also see my other and similar answer about supporting AsciiDoc: #1337. The considerations for supporting both formats are very similar.

[villanella]

@stanislaw Is it possible to support markdown with tags in yaml-frontmatter format (like in Doorstop beta) to have spec files with *.md extension instead of *.sdoc? For us it's very useful for integrations, and makes possible editing and quick viewing files in external editors or in Github/Gitlab with markdown support.

AsciiDoc is also good format that is used by non-programmers (technical writers) in my organization. It's important to have native file extension for rendering it in the existing web-infrastructure.

[stanislaw]

You are asking about something that is somewhat perpendicular to what StrictDoc is and where it is going.

StrictDoc had started as a fork of Doorstop but moved away from Markdown or YAML since then because of the limitations of these formats, see https://strictdoc.readthedocs.io/en/stable/strictdoc_02_faq.html#how-did-the-sdoc-text-language-become-what-it-is and https://strictdoc.readthedocs.io/en/stable/strictdoc_02_faq.html#how-did-the-sdoc-text-language-become-what-it-isDoo.

StrictDoc uses a custom markup exactly to address the need of having requirement nodes with meta information as well as support nested structures, which are required by things like StrictDoc's [GRAMMAR] and requirement REFS and RELATIONS. Supporting all of that using Markdown has proven to be very difficult, because Markdown does not seem to be designed for handling meta information. Adding YAML front matters as a workaround would have been another hack to make things work, but maintaining such an extension did not look promising.

If you are really keen on doing something with StrictDoc and Markdown, we could arrange a meeting where you could explain your use case: which kind of requirements do you need to create and how do you want to integrate them with your other software workflows. Just email me if you are ready to e-meet.

[stanislaw]

Here is something what I would consider a step zero for implementing Markdown:

There are quite realistic files with SDoc requirements: https://github.com/nmfta-repo/vcr-experiment/blob/main/01_gateways.sdoc and https://github.com/zephyrproject-rtos/reqmgmt/blob/main/docs/zephyr_01_high_level_requirements.sdoc. I would like to see the examples of how these documents would be modeled with just Markdown. It would be interesting to see the examples with Markdown/YAML and Markdown/XML.

The complete documents do not have to be copied, only their most interesting and complex fragments. For example, the GRAMMAR declaration and an example of a REQUIREMENT that has many multiline fields, like the requirements from the vcr-experiment.

I am curious to see an example of how a Markdown equivalent would look like for a requirement has many single- and multi-line fields, for example this one or some other: https://github.com/nmfta-repo/vcr-experiment/blob/main/01_gateways.sdoc#L143.