Composite GitLab Flavored Markdown Document
I would like to use GitLab Flavored Markdown (GFM) to create and edit a composite markdown document, that is made up of other markdown documents, with all docs under git VCS in Gitlab. Kinda like a merge document in MS Word with a bit of templating built in.
From what I have read Sphinx does this kind of thing, but I want some of the auto linking features inside GFM. GFM can do some of this with link IDs .
- I want to create a master document, that mainly has headers links to the other sub documents. Sphinx does this in a hierarchy structure. (A master could contain other masters as a sub document.)
- I want the sub documents that have just the body to go under the header in the master document.
- I want the sub documents to be used in multiple master document, so the same section could have different headings and locations in different masters.
- I want the sub documents to allow some type of comment syntax, that would not be included when the master and sub documents are combined. Similar to a MS word template, where it describes what to write in a section, but I want to still be able to reference/see that text while I am writing the sub document.
- I want Gitlab to auto create the combined document, where it place all the sub document in the master doc at the link location.
- Any header in the sub document would need to be shifted to be more than level of the header it falls under. In most case, the header above will be h2, thus an h1 in a sub document would need to become an h3 in the combined document.
- I want to be able to edit the combined document, and have the changes applied to the master and sub documents.
- I want to be able to lock the combined document, and have the master and sub documents also locked, so that no additional changes can be made.
- I want to be able to export the combined to other document systems, like Sphinx or MS Word where I can apply additional formatting for presentation and printing, like adding an auto table of contents, applying headers and footer, adding a water mark, adding a cover page, etc.
- It would be nice if hyperlink could be converted to the exported format. So, if the link is to another document, assuming the other document would also be exported in the same format and be in the same dir.
With this, once a master document is created along with its sub documents with just the comments and common elements, this could server a template to create multiple combined documents in different projects. All you would need to do is copy original master and sub documents, and then edit from there.
Links / references
Below is IEEE SRS header template with some of description of what to write in the section
Please provide a brief introduction to your project and a brief overview of what the reader will find in this section.
Provide a short description of the product whose requirements are listed in this document.
Definitions, acronyms & abbreviations
List the various users that you anticipate will use this product. Describe the pertinent characteristics of each user. Certain requirements may pertain only to certain users.
Describe any items or issues that will limit the options available to the developers. These might include: hardware limitations (timing requirements, memory requirements); interfaces to other applications; specific technologies, tools, and databases to be used; parallel operations; language requirements; communications protocols; security considerations; design conventions or programming standards (for example, if the customer’s organization will be responsible for maintaining the delivered software).
Assumptions and dependencies
Apportioning of requirements
External interface requirements
If possible provide a short description of the connections of this software with other software for example databases, operating systems, tools, libraries, and integrated commercial components.
Classes for classification of specific requirements
If there are performance requirements for the product under various circumstances, state them here and explain their rationale, to help the developers understand the intent and make suitable design choices. If possible provide different performance requirements based on the information you collected from the client. Example A database query shall not take more than 15 seconds.