Documentation

• 1: Running the Neurodesk Site Locally (Hugo + Docsy)
• 2: Contribute to Neurodesk.org

1 - Running the Neurodesk Site Locally (Hugo + Docsy)

1. Prerequisites

• Git
• Go (required for Hugo modules)
• Hugo extended version (0.121 recommended). See https://github.com/gohugoio/hugo/releases for Hugo releases.
  • Download for Mac OS and Linux.
  • Download for Windows

2. Cloning the repository

This step is the same for macOS, Windows, and Linux.

Using SSH

git clone --recurse-submodules git@github.com:NeuroDesk/neurodesk.github.io.git

or

Using HTTPS

git clone --recurse-submodules https://github.com/NeuroDesk/neurodesk.github.io.git

If you cloned without –recurse-submodules

Run the following command to pull submodules

git submodule update --init --recursive --remote

3. Start local hugo server

On Windows:

1. Extract the hugo.exe binary from the ZIP file into the root of your neurodesk.github.io directory.
2. Open PowerShell or Git Bash, then run:

.\hugo.exe server --disableFastRender

3. Once started, your dev website will be accessible via http://localhost:1313

On Mac:

1. Extract, move, and authorize the Hugo binary:

cd ~/Downloads  #edit according to location of file
tar -xvzf hugo_extended_0.115.4_darwin-universal.tar.gz #unzip the file
chmod +x hugo #Make the hugo file executable
sudo mv hugo /usr/local/bin/hugo-extended #move file to bin folder

2. Verify your Hugo installation

hugo-extended version #if it is your first time running this on a Mac, you will see a security warning

You should expect something like this (look for the mention of extended to be sure it worked)

hugo v0.121.0-e321c3502aa8e80a7a7c951359339a985f082757+extended darwin/arm64 BuildDate=2023-12-05T15:22:31Z VendorInfo=gohugoio

Once installed, you can run the server for Mac using:

hugo-extended server --disableFastRender

Once started, your dev website will be accessible via http://localhost:1313

4. Update docsy theme submodule (optional)

git submodule update --remote
git add themes/
git commit -m "Updating theme submodule"
git push origin main

2 - Contribute to Neurodesk.org

This applies if you with to submit a new tutorial or amend content on a page. Our website is mostly written in Markdown (.md files). We include the basics of writing in Markdown on this page.

Table of contents

• Create your own copy of neurodesk/neurodesk.github.io repository
• Create your content or make your modifications
• Contribute your new content to the official documentation
• Formatting guidelines
• Code blocks
• Images
• Alerts and warnings
• Tables
• Lists

Create your own copy of neurodesk/neurodesk.github.io repository where you will be able to make modifications

Begin by creating a copy of our documentation that you can edit:

1. Visit the GitHub repository for the Neurodesk documentation.
2. Fork the repository.

Create your content or make your modifications

1. Clone your forked version of our documentation to a location of your choice on your computer.

This step is the same for macOS, Windows, and Linux.

Using SSH

git clone --recurse-submodules git@github.com:NeuroDesk/neurodesk.github.io.git

or

Using HTTPS

git clone --recurse-submodules https://github.com/NeuroDesk/neurodesk.github.io.git

If you cloned without –recurse-submodules

Run the following command to pull submodules

git submodule update --init --recursive --remote

The URL for the repository can be copied by clicking on the button highlighted below:

2. Now, you can open your copy of neurodesk.github.io using the editor of your choice (we recommend vscode). Before making changes to the current repository, the best practice is to create a new branch for avoiding version conflicts.

• Create a branch:

git branch tutorial-template

• Checkout the branch you want to use for the addition or changes you’d like to make

git checkout tutorial-template

• Confirm you are in the right branch:

git branch

3. Within your cloned environment, navigate to where you’d like to make your changes.

For example, if you’d like to create new tutorial content, go in neurodesk.github.io/content/en/tutorials-examples/tutorials/ and then navigate to the subfolder you believe your tutorial belongs in (e.g. “/functional_imaging”)

4. Create a new, appropriately named markdown file to house your content (e.g. for a tutorial about physiology, you might call it “physio.md”). Images need to be stored in the /static directory - please mirror the same directory structure as for your markdown files.

5. Open this file and populate it with your content! You’re also welcome to look at other tutorials already documented on our website for inspiration.

Contribute your new content to the official documentation

1. Once you are happy with your content, to avoid merge conflicts, rebase your branch with the main branch, which should be synced with NeuroDesk/neurodesk.github.io:main (on GitHub check if your repo is synced and locally checkout the main branch and run git pull).

git rebase main

You might have to correct some merge conflicts, but vscode makes it easy.

2. Commit all your changes and push these local commits to GitHub.

3. Navigate to your forked version of the repository on GitHub and switch branches for the one with your additions.

4. Now, you can preview the changes before contributing them upstream. For this, if this is your first time to run the Action build, click on the “Actions” tab and enable the Actions (“I understand my tutorials…”). You can run the workflow by clicking on each of them in the left sidebar.

5. Then you need to open the settings of the repository and check that Pages points to gh-pages, and when clicking on the link, the site should be there.

6. To contribute your changes, click “Compare & pull request” and then “Create pull request”.

7. Give your pull request a title (e.g. “Document PhysIO tutorial”), leave a comment briefly describing what you have done, and then create the pull request.

8. Someone from the Neurodesk team will review and accept your changes, which will appear on our website soon!

Thanks so much for taking the time to contribute content to the Neurodesk community! If you have any feedback on the process, please let us know on github discussions.

Formatting guidelines

As seen throughout this tutorial, you can embellish your text using markdown conventions; text can be bold, italic, or strikethrough. You can also add Links, and you can organise your content with headers, starting at level 2 (the page title is a level 1 header):

Level 2 heading

You can also include progressively smaller subheadings:

Level 3 heading

Some more detailed information.

Level 4 heading

Even more detailed information.

Code blocks

You can add codeblocks to your content as follows:

# Some example code
import numpy as np
a = np.array([1, 2])
b = np.array([3, 4])
print(a+b)

Or add syntax highlighting to your codeblocks:

# Some example code
import numpy as np
a = np.array([1, 2])
b = np.array([3, 4])
print(a+b)

Advanced code or command line formatting using this html snippet:

# Some example code
import numpy as np
a = np.array([1, 2])
b = np.array([3, 4])
print(a+b)
[4 6]

You can also add code snippets, e.g. var foo = "bar";, which will be shown inline.

Images

To add screenshots and images to your content, create a subfolder in /static with the same file structure as in your content markdown file. Add your screenshot to this folder, keeping in mind that you may want to adjust your screenshot to a reasonable size before uploading. You can then embed these images in your tutorial using the following convention:

For a filename.png in a /content/en/tutorials-examples/subject/tutorial1/markdownfile.md use

![filename](/static/...<fullpathhere>.../filename.png '[filename')

For example: EEGtut1.png in /content/en/tutorials-examples/tutorials/electrophysiology/eeg_mne-python.md would be

![EEGtut1](/static/tutorials-examples/tutorials/electrophysiology/eeg_mne-python/EEGtut1.png 'EEGtut1')

Alerts and warnings

You can grab the reader’s attention to particularly important information with quoteblocks, alerts, and warnings:

This is a quoteblock

You can also segment information as follows:

There’s a horizontal rule above and below this.

Or add page information:

Tables

You may want to order information in a table as follows:

Lists

You may want to organise information in a list as follows:

Here is an unordered list:

• Rstudio
• JASP
• SPSS

And an ordered list:

1. Collect data
2. Try to install analysis software
3. Cry a little

And an unordered task list:

• Install Neurodesktop
• Analyse data
• Take a vacation

And a “mixed” task list:

• writing
• ?
• more writing probably

And a nested list:

• EEG file extensions
  • .eeg, .vhdr, .vmrk
  • .edf
  • .bdf
  • .set, .fdt
  • .smr
• MEG file extensions
  • .ds
  • .fif
  • .sqd
  • .raw
  • .kdf

Need Help?

If you have questions or would like feedback before submitting:

• Open a discussion

We appreciate your contribution to the Neurodesk community and reproducible science.