Contributing to nmrXiv Documentation ​

This website is based on the Vitepress framework which is a Static Site Generator (SSG) designed for building fast, content-centric websites. To put it briefly, VitePress processes your source content written in Markdown, applies a theme, and produces static HTML pages that can be effortlessly deployed on any platform.

Forking ​

First, you need to fork the nmrXiv repository on GitHub

Installation ​

Open the forked repo in your local in the editor of your choice such as Visual Studio Code and follow the below steps to start with:

    npm install

    npm install

    npm run docs:dev

    npm run docs:dev

Your local documentation site is ready and would be running on http://localhost:5173/

Branching ​

Whenever you want to edit a page, please do the following:

• Create a new branch for that page from the "development" branch.
• Make your modifications on that branch.
• Create a pull request on GitHub for your fork to "development".

Afterwards, the maintainers will review your changes and merge them.

How to ​

Adding a New Page ​

• Go to the docs directory located at root location.
• Add a new file there or folder.
• Name your file complying with our conventions (kebab-case-of-small-letters).
• Give it the extension ".md".
• Configure the newly added file to docs/.vitepress/config.mjs.

Headings ​

To create a heading, add one or more # signs in front of the word or phrase. The number of # you use should correspond to the heading level. Many # indicates a low level.

Escaping Signs ​

To show signs specified in the Markdown syntax, escape them with "".

Links ​

Links can be added via Markdown:

In Markdown:

[Text to be shown on the page](actual link)

[Text to be shown on the page](actual link)

Lists ​

Ordered List ​

Enter the number you want your list to start with, enter a dot and a space, then enter your text. When you hit enter, the next number will be generated automatically.

2. First line.
3. Second line.
4. Third line.

2. First line.
3. Second line.
4. Third line.

Output:

2. First line.
3. Second line.
4. Third line.

Please note, if you enter random numbers with dots, the generated list will still be ordered based on the first number!

2. First line.
5. Second line.
2. Third line.

2. First line.
5. Second line.
2. Third line.

Output:

2. First line.
3. Second line.
4. Third line.

Unordered Lists: ​

Use either * or - at the beginning of the line, then enter a space and then your text.

* First line.
- Second line.

* First line.
- Second line.

Output:

• First line.

• Second line.

Code Blocks ​

Code blocks enable highlighting your code and its syntax based on the language. To use code blocks:

1. Wrap your code with three backticks.
2. Add the right language.
3. Insert your code.

For instance:

```js

Example

```

Which will look like this:

<span style="color:yellow;">Example</span>

<span style="color:yellow;">Example</span>

For a list of the supported languages, please visit the link. It is common to use "bash", "html", "js", and "md" in this documentation. Please use "Bash" code blocks for errors too.

Images/gifs ​

Images/gifs can be inserted in a centered mode with a specified width using HTML. Please use the following block and change the path to your image, along with the width and caption. If you have many images related to one topic, please group them in one folder. All images are to be added to /static/img folder.

<p align="center">
<img src="/img/project/view.png" width="1000"/>
<figcaption>Private project view</figcaption>
</p>

<p align="center">
<img src="/img/project/view.png" width="1000"/>
<figcaption>Private project view</figcaption>
</p>

SVG ​

SVGs need special treatment. First import them as React component, and then insert them in your text with className="logo":

import Sun from '@site/static/img/sun.svg'
<Sun title="Sun" className="logo" width={"30px"} height={"30px"} />

import Sun from '@site/static/img/sun.svg'
<Sun title="Sun" className="logo" width={"30px"} height={"30px"} />

Tables ​

| Header 1 | Header 2 |
|---|---|
| Field 1  |  Field 2 |

| Header 1 | Header 2 |
|---|---|
| Field 1  |  Field 2 |

Output:

Info Boxes ​

Custom containers can be defined by their types, titles, and contents.

::: info
This is an info box.
:::

::: tip
This is a tip.
:::

::: warning
This is a warning.
:::

::: danger
This is a dangerous warning.
:::

::: details
This is a details block.
:::

::: info
This is an info box.
:::

::: tip
This is a tip.
:::

::: warning
This is a warning.
:::

::: danger
This is a dangerous warning.
:::

::: details
This is a details block.
:::

Inserting Downloadable Files ​

If you want to provide one or multiple file(s) to be downloaded directly from the documentation, upload them to the files folder in GitHub, and insert a Download Button with the file path(s), separated by a comma, in files and the text to be shown on the button in text:

import { DownloadBtn } from '@site/download-files.js'

<DownloadBtn files={['/nmrxiv-docs/static/files/test-file.txt']}  text={"Download test file here"}/>

import { DownloadBtn } from '@site/download-files.js'

<DownloadBtn files={['/nmrxiv-docs/static/files/test-file.txt']}  text={"Download test file here"}/>

Formatting ​

Bold ​

<b>Example</b>

<b>Example</b>

Output: Example

Italics ​

<i>Example</i>

<i>Example</i>

Output: Example

Highlighted Elements ​

`Example`

`Example`

Output: Example

Line Breaks ​

Add two blank lines (two "enter"s) where the line break is needed to be.

Color ​

• Colored letters:

<span style="color:yellow;">Example</span>

<span style="color:yellow;">Example</span>

Output: Example

• Colored background:

<span style="background:yellow;">Example</span>

<span style="background:yellow;">Example</span>

Output: Example

Strikethrough ​

<del>Example</del>

<del>Example</del>

Output: Example

Conventions ​

Hyperlinks ​

We would recommend the intensive use of hyperlinks instead of plain text whenever possible. The intro of this page is a good example of that.

Bold Text ​

All bolded terms in this documentation can also be found within the user/developer interface.

Tables ​

To maintain a consistent view throughout the table, the first letter from the first word will always be capitalized (unless it is a unit). Full stops will be used when the correct language requires them. The following table provides more details and examples.

Capitalization ​

Please always capitalize:

• The first letter of the first word, unless it is officially written with small letters, e.g., "nmrXiv".
• Headings: The first letter of each word except articles, conjunctions, and prepositions with less than four letters. e.g., "Contributing to nmrXiv Docs".

Please note: Prepositions are dealt with as normal words and are capitalized when applicable in the following cases:

• If they are part of the verb: "Starting Up the Application".
• If they have more than four letters: "Further Steps After Installation".

Highlighting Elements ​

Highlighted Elements should be used with files and folders names, and to highlight words where bolding is not applicable.

Images ​

Images are to be added directly after the corresponding paragraph.

Citations ​

When citing nother resource, please add a number at the end of the cited section within brackets. For instance: "This is a cited line.[1]". At the bottom of the page, pleas add a new paragraph highlighted with one "#" and name it as "References". Then provide the numbered list of references as persistent links.