Template article
This article provides you with the most important information on how to write an article for the NFDI4Earth Living Handbook.
It covers the metadata describing Living Handbook articles, the recommended structure of articles, and how to deal with figures and other linked or embedded content and references. Articles in the Living Handbook are written in Markdown. Therefore, this article also provides some instructions on how to do text-formatting and inclusion of external content is done in Markdown. Although submission of articles in Markdown is strongly encouraged, we also provide this template in the docx format as alternative. Please note that instructions below vary between the documents if they are specific for the respective file format.
Metadata
To view the metadata, please read the raw version of the article. In the raw version, the top part of this document, enclosed in ---, contains the metadata associated with the articles, i.e., information that describes your article. Please fill it in/replace the examples according to the explanation provided for each metadatum. Afterwards, you can delete any line starting with #.
Structure of NFDI4Earth Living Handbook articles
Except for some specific types of articles, there is no specific outline for Living Handbook articles. Instead, the content should be arranged in a way that suits the topic best. To ease comprehensibility of the content, we strongly recommend following a "spiral out" approach. This means that the core of the topic is explained first, then all its main aspects are briefly developed before detailed accounts for some or all of them are given. Structuring content this way allows readers unfamiliar with the content to acquire general knowledge before encountering expert knowledge.
If a topic is very complex, it might be better to split it up into multiple articles and develop the different aspects in detail there, while the "main" article provides a summary/review style perspective of the topic and refers to them.
Media and other linked/embedded content
Media and other content can significantly enhance the comprehensibility on an article. Therefore, any type of media and other non-text content can be included in an article. This also includes interactive content such as widgets, 3D models, maps or Jupyter Notebooks. Please find in the section Writing in Markdown a list of how different media can be included when preparing the article in markdown. If the type of content you want to include is not listed there, please get in touch with the editors via nfdi4earth-livinghandbook@tu-dresden.de to check how it can made possible.
References
References are important for supporting the content of an article. In addition, they provide important entry points for an in-depth study of the topic beyond the article. Therefore, all content must be supported with exemplary suitable references. Open access publications/resources should be preferred. While there is no need for providing an exhaustive reference list for the article, please consider adding an "Additional resources" section to facilitate additional research on the topic by the readers.
Writing with Markdown
The NFDI4Earth Living Handbook is written in Markdown, which ensures a high degree of flexibility on a technical level while having a high degree of readability as raw text. The general Markdown syntax is well explained in this Cheat Sheet. In addition, the NFDI4Earth Living Handbook supports some additional syntax.
Including media/external content
places an image at the location LINK with its caption placed under it and the Alt text being accessible to screen readers (it will also be displayed, if the link is broken). Numbering will be done automatially.[](https://www.youtube.com/watch?v=YOUTUBE-ID)includes the Youtube video identified by its YOUTUBE-ID. Analogous to images, the caption will be displayed below the video and the Alt text should contain a description/summary of the video for screen readers.- Raw HTML code can be included, allowing to, e.g., copy-paste snippets provided via the "Embed" button.