Skip to main content
Research Support Handbook

Contributing

You can contribute to the Research Support Handbook by making small edits, writing entirely new topics, or writing guides. All contributions are welcome and appreciated, small and large. There are two ways to contribute: via GitHub or by using the contribution portal. If you are in need of specific information, you can skip ahead using the table of contents.

Contributing portal

We offer a portal to reduce the barriers to contribute to the Research Support Handbook. You only need an internet connection and articulate what you want us to include. No accounts necessary 😊

Note

Open the contribution portal by clicking here or copy-pasting: https://ez-github-contributor.netlify.app/

You can report issues you find with the Research Support Handbook using the “Report a problem” tab. This is a way for you to share your feedback with us.

You can propose new topics or guides to the Research Support Handbook using the “Propose new page” tab. This will be considered for inclusion. Please mention whether it should be a topic or a guide. The text editor allows you to use rich text formatting.

Warning

The portal does not save your work. Use the portal when you are ready to submit your work, but do not use it to manage your submissions.

Screenshot of the contributor portal

If you want to be credited with contributing, please share your name. If you’d like to hear back about what was done with your feedback or proposal, please also provide a direct way to contact you. Once you have submitted the contribution, the editors will decide how to add your contribution to the handbook. Take a look at the Editor’s guide to learn more about what criteria they consider.

Contributing via GitHub

Note

For the next steps you need a GitHub account to contribute. You can create one directly on GitHub.

Suggesting edits

The easiest and quickest way to contribute to the book is make suggested edits. On each page you will find a button reading “Edit this page” (usually on the right).

Screenshot of a handbook topic, with a red box on the right hand side of the page indicating where to find the “Edit this page” button

When you click that, you will immediately be taken to GitHub to edit the text of that specific page. You may be prompted to create a fork (forking) in case these are your first edits.

Screenshot of the GitHub file editor, with some changes made and the “Commit changes” button active

Once you made your edits, you are ready to commit (save) your changes and submit your pull request, requesting those changes to be included in the handbook.

Adding a topic

To add a new topic, you need to create a new file ending in .qmd in the topics folder (e.g., topics/example.qmd). You can do this by visiting the handbook page on GitHub and clicking Add file -> New file.

Screenshot of GitHub highlighting where to find the “New file” button

When you click this button you may be asked to fork the repository. This is not a problem so go ahead!

The topic itself needs to be written in Markdown. Every topic must be a noun/noun phrase and contain the title as such:

---
title: Example topic
---

Section headings are second level headings (e.g., ## Section). You can add all needed information as you want, but please mind that topics are supposed to short and self-contained for readers of the Research Support Handbook.

After that, you are ready to submit your pull request! The reviewers will help you place the topic in the right place of the book.

Adding a guide

To add a new guide, you need to create a new file ending in .qmd in the guides folder (e.g., guides/example.qmd). You can do this by visiting the handbook page on GitHub and clicking Add file -> New file.

Screenshot of GitHub highlighting where to find the “New file” button

When you click this button you may be asked to fork the repository. This is not a problem so go ahead!

Every guide title must reflect the question the guide answers. Add the title by adding the following information at the top of your document:

---
title: How do I create a guide?
---

Section headings are second level headings (e.g., ## Section). The guide itself needs to be written in Markdown.

You can re-use topics literally in your guides. For each topic you want to include, you can either mention so on a line surrounded by whitespaces:

INSERT TOPIC: DATA MANAGEMENT PLAN

This will tell the editorial team to include that topic there. Please be specific in naming the topic. You can also directly include the topic yourself directly using the following code:


## Topic name

    ```{.include shift-heading-level-by=2}
    ../topics/replace-with-filename.qmd
    ```

You need to count the heading level in your guide to identify your shift number. In this case, there are two ## so we shift by two. You can verify the filename directly, but it should correspond to each word separated by a minus sign (for example, data-management-plan.qmd).

After that, you are ready to submit your pull request!

Adding a tool

Tool descriptions always consist of multiple pages. To add a new tool it is best to work locally, for example in VScode.

If a new tool needs to be added do the following (using SPSS as an example):

Copy template

  • Copy the folder /tools/_template to /tools/spss. Always use lowercase for folder and file names.

Set the left sidebar

  • Edit the /tools/spss/_sidebar.yml file and rename dummy to spss (or SPSS in titles). Do not forget the id, which should be unique for the tool.
website:
  sidebar:
    - id: sb-spss 
      collapse-level: 4
      contents:
      # Title that shows up at the top of the sidebar
        - section: SPSS
          href: tools/spss/index.qmd
          contents:
          - href: tools/spss/index.qmd # Mandatory, start page 
            text: What is SPSS?
          # Always use paths relative to the root of the site.
          - tools/spss/cost_access.qmd # Mandatory
          - tools/spss/contact_support.qmd # Mandatoty
          - tools/spss/quick_start.qmd # Mandatory
          - tools/spss/faq.qmd # Optional, delete if not necessary
          - tools/spss/known-issues.qmd # Optional, delete if not necessary
          - section: Documentation # Optional, delete section + contents if there are none
            contents: # Add additional documentation pages here. Subsections are possible
            - tools/spss/some-how-to.qmd 
  • Add a reference to this sidebar in /_quarto.yml in the metadata-files section (keep this in alphabetical order for clarity):
...
metadata-files:
  ...
  - tools/snellius/_sidebar.yml
  - tools/spss/_sidebar.yml
  - tools/vucomputehub/_sidebar.yml
  - tools/yoda/_sidebar.yml

Add the tool to the Tools overview page

  • Copy a logo image to the /public folder (use Google image search to find one). Preferred format is svg.
  • Edit the metadata section in /tools/spss/index.qmd. Set the application name as title, the path to the logo image and one or more appropriate categories:
---
title: SPSS # Add link to this page to ./tools.qmd title must be the tool name
categories: [Statistics] # categories appropriate to this tool
image: '/public/spss-logo.svg' # Make sure to add a logo
---

## What is it?

## What can it be used for?
  • Edit the metadata section of /tools.qmd, add /tools/spss/index.qmd to the listing contents to make the tool visible on the tools page:
---
title: Tools
listing:
  id: tools
  template: ./_templates/accordion-logo.ejs.md
  contents:
...
    - tools/snellius/index.qmd
    - tools/spss/index.qmd
    - tools/vucomputehub/index.qmd
    - tools/yoda/index.qmd
...
---

...

Edit the pages

  • Make sure to edit at least the index.qmd (What is?), cost_access.qmd, contact_support.qmd and quick_start.qmd files.
  • Delete unused files from the tool folder and the _sidebar.yml.
  • You can also add extra pages as needed. Make sure to add them to the _sidebar.yml file under the Documentation section. If you need extra subsections under Documentation you can add them to _sidebar.yml as needed.

After that, you are ready to submit your pull request!

Editing multiple files

There are situations in which you need to edit multiple files. If you carry out all edits in separate pull requests, this may be a long and repetitive task. Instead, you can change multiple files at once in a single pull request.

Note

In case you want to edit multiple files in one go, here’s a video to help you along the way!

Video describing the steps to use the GitHub editor to edit multiple files

Submit a pull request

Once you have made suggested changes, a pull request is the way for you to ask for your changes to be incorporated into the Research Support Handbook. The handbook editors will review what you wrote, ask some questions, and accept or decline your contributions.

We recommend keeping your suggested changes small or limited in scope, and explaining why you are suggesting these changes. It is more likely your changes are included when you are fixing a typo or adding a paragraph, and less likely if you are revising the entire handbook. It is also more likely they are included if you explain why you are suggesting the changes, rather than dropping by and making edits without any context.

If you are adding a new topic or guide, it is definitely recommended to open an issue first to see whether there is a need for it (and maybe you’ll find collaborators!).

During the review process you may be asked to update your changes, or revisions may be added by the people maintaining the handbook. It is helpful if you keep an eye on your GitHub account to ensure timely responses to help the process along. By contributing, you become part of the process :blush:. Once you have submitted the contribution, the editors will decide how to add your contribution to the handbook. Take a look at the Editor’s guide to learn more about what criteria they consider.

Writing text

The book is created using Markdown - you can get familiarized with the basic syntax on the Markdown website. The getting started quick items are:

# Heading level 1
## Heading level 2
### Heading level 3

You simply write text as you are used to. To make something *italic*, **bold**, or ***bold and italic***.

> this is how you add quotes

- or lists
- that can go on
- and on

If you want to add code, use references, create links, or footnotes - it is all possible. We will expand examples here based on your needs, so if you need help, let us know by reporting an issue!

Adding images

In markdown, you can easily add images and alt text at the same time. We require alt text on all images, and if you are contributing an image, you can best describe its value in the text.

You add images by using:

![Alt text](URL)

If you want the image to be hosted in the Research Support Handbook, use the following steps:

  1. Add the image you want to the public/ folder
  2. Mark the exact filename
  3. Use ../public/<filename> as the URL for the image (for example ../public/image.png)

More information about GitHub

We use GitHub to create this website automatically, and to manage all the incoming updates. You do not need to know how it works entirely, but we want to help you understand some things so you are not confused.

Repository

A repository on GitHub is like a folder on your computer. This can be many things, depending on what files it contains.

When we mention a repository here, we mean that we want you to look at a specific folder. The repository for this website for example can be found on GitHub directly. You will always be contributing to a repository, in order to contribute to the handbook.

Forking

A repository is owned by one or multiple people on GitHub. If you are not one of them, you can create a copy of the repository (folder) to make your edits in. This act of creating a copy is called “forking.”

When you create a copy, you do not have to worry about accidentally removing or destroying the handbook. Your changes are not reflected in the website until you submit a pull request.

Adding references

If you want to include references throughout the handbook, we recommend you do so in the following way.

Add the BibTex

You can find the relevant BibTeX information using a tool like the DOI to BibTeX converter. Counterintuitively, it also works on ISBNs for example.

After you found the BibTeX information, you add it to the references.bib file (preferably all the way at the bottom). Example BibTeX information is:

@ARTICLE{example-code,
  title     = "Example Title",
  author    = "Author, Example"
  journal   = "Example Journal",
  year      =  2042,
  copyright = "https://creativecommons.org/licenses/by/4.0",
  language  = "en"
}

Add the citation

To add the citation to a page, you use [@example-code] or @example-code.

@example-code will result in an in-text citation, like “Author (2042).”

[@example-code] will result in a regular citation such as “(Author, 2042)”.

For more details on citations, see also the Quarto help page on citations.

Rendering handbook locally

Sometimes you may want to preview the changes you are making to the handbook. That is possible in most cases, but requires you to install some software. You need to install Quarto and assuming a successful installation, you then need to run the following code in your terminal1:

# Clone the git repository
git clone git@github.com:ubvu/open-handbook.git
# Go into the right folder
cd  open-handbook
# Render the handbook
quarto render .

This will create a file called _site/index.html. You can now open the rendered website in your browser by running:

# For Windows machines, use
start <browser-name> _site/index.html
# For Mac machines, use
open _site/index.html
# For Linux, it could depend on the exact Linux operating system, but you could try first
xdg-open _site/index.html

Note that you should not copy the < and >, they are written here to indicate where the browser name should come.

You can also make changes locally and push them to the github repo to open a new branch. The procedure for this in your terminal is as follows:

# Navigate to the folder where the file you want to edit is located
cd <foldername>
# Open the file to edit
nano <filename>
# Edit the file and save by using `Control + O`. Exit nano by `Control + X`
# Add the file to the staging area
git add <filename>
# Commit the edits
git commit -m "<commit message>"

Once you are done editing, you can also render the page to check that all is well. If you have already used quarto render . once, you can simply re-render the page you were working on, using quarto render <path/filename.qmd>, e.g. quarto render . /tools/yoda/index.qmd, which is a lot quicker. Note that you should not copy the < and >, they are used here to indicate where to add file and folder names, or a suitable commit message.

Once you are happy with the result, you can push the new version back to the github repository online:

# Push the edits to the remote (online) repository. You can only push to a new branch: the main branch is protected.
# If you do not have editing rights to the handbook repository, you would be pushing to your fork.
git push origin main:<new-branch-name>
# You may have to authenticate using your SSH key.

Note that you should not copy the < and >, they are written here to indicate where file and folder names should be written. After doing this, your new branch is opened in the repository on GitHub and you can create a pull request.

This procedure requires some background knowledge on working (with git) in the command line. The resources below give more explanation:

We do not guarantee this will work immediately, but should cover most instances. If you are looking to contribute and want to render things locally, try this first, and if you run into any issues, let us know in an issue report. We’re happy to try our best if you share your error messages 😊

Using VS Code to contribute

If you are planning to make multiple contributions to the Handbook, working in the GitHub web interface can get cumbersome. In that case we suggest you use an IDE (Integrated Development Environment) to create and edit pages. An IDE is a text editor that has lots of extra functionalities for developers, such as integration with Git. VS Code is a widely used, free, IDE and it is very well suited to edit Markdown files and has integrated Git & GitHub support. This allows you to work on your edits on your laptop whenever you want, preview them using the Quarto client and Push your changes to GitHub. No special knowledge of the Git Commandline is necessary.

Install VS Code

VS Code is available for Windows, Mac and Linux. Install it from https://code.visualstudio.com/Download.

Note that VS Code is a Microsoft product, but the source code of VS Code is open source. The VS Code version you download from the above link is not, and it contains telemetry/tracking. A completely open source version without telemetry is available from https://vscodium.com, the functionality is the same.

Install the Quarto extension for VS Code

Install the Quarto Extension to make sure VS Code understands the Quarto format.

Note that unfortunately the Preview functionality does not work very well with a project as large as the Handbook.

Make sure Git is installed

  • Open VS Code and click on the Git icon on the left. If you do not have Git installed you can do so from here, the download button will lead you to https://git-scm.com/downloads, you do not need the GUI client.

Download Git

Default Editor - During the install you can set VS Code as default editor

Recommended PATH option
  • Keep defaults for the rest.

  • Open a command prompt to set your username and email address, without this you cannot push your changes to GitHub.

Set git username and email

Create a root folder

Create a folder where your handbook copy and other code projects will be stored. For example on Windows C:\users\<username>\VS Code.

Note that it is not advisable to store code projects in a folder which is synced with OneDrive (such as the “Documents’ folder), OneDrive will have problems syncing the many small files that git uses. The same applies to SURFdrive and Research Drive. You will push changes to your code projects to github so there is no need to make extra backups.

Create a Fork of the Handbook

Fork button - Click Fork button at the top right.

Your new Fork - You end up with all the code in your personal account.

Clone your Fork

  • Go to the Git Tab (or click File > New window), there you will see the option to “Clone Repository”.

Clone Repository

Clone from GitHub - You see the option “Clone from GitHub”.

Sign in to GitHub

Allow GitHub sign in
  • If you have never signed in with Git before you will be asked to do so. Click Allow.

  • The GitHub Sign In page will be opened in the Browser. Login as usual.

Select the Fork you created earlier

  • Once you are signed in you can select from a list of repositories.

Select Forked repository - Select the Fork you created earlier.

Clone to code folder - Select your code root folder.

  • A folder called open-handbook will be created in that folder and you can open it in VS Code.

Editing

Now you have a full copy of the Handbook on your laptop. Of course you are not working on the Handbook directly, but on your Fork.

You can make changes to the actual Handbook by making changes to your Fork and creating a Pull Request. The Pull Request will be opened in the ubvu open-handbook repository. The editors can then approve your request, perhaps after suggesting some changes, and your changes will be merged to rdm.vu.nl.

The handbook is a collaborative effort, multiple people will be making changes to multiple files at the same time. To prevent 2 or more contributors making changes to the same file you should keep the number of files you change in your Pull requests small, preferrably just one page at a time. The best way to do this is to start by creating a branch for the changes you want to make.

Create a branch

Create Branch

Provide a name - Provide a name for the branch. Keep it short and descriptive, this is mainly for yourself so you can easily remember what you created the branch for.

VS Code will automatically switch to the branch. You can always see the branch you are working on in the bottom left of the Window.

Branch name

You can click on the name there to switch the branch you are working on.

Remember your changes are tied to the branch. If you would switch from the zenodo_topic branch to the main branch you will no longer see the changes you made to the Zenodo topic page. But if you have committed your changes they will be visible again once you switch back.

Editing the page

VS Code is basically just a text editor. Open the file you want to work on by double clicking or right click to create a new one in the “Explorer”.

Tip

The Quarto Extension includes a Visual Editor with which you can format Quarto pages without typing Markdown code.

  • Work on your page and save your changes (Click File > Save or use CTRL+S).

Changes
  • VS Code will show you the changes with respect to the branch. Now you can commit

Commit changes

  • Click on the Git icon on the left.

Commit message- Set a short descriptive commit message, click the plus sign next to the files you want in your commit, and click commit.

View changes By double-clicking on a Modified file you will see a visual representation of your changes.

Publish Branch

Now you have committed your changes to the local git repository on your laptop. You will also need to publish the branch to github, so it gets updated as well.

Publish Branch

Branch Published You will be able to view the branch on github.

VS Code will now allow you to Sync (Push and Pull) your commits to the branch on GitHub.

Create a Pull request

Once you are happy with the changes you made you can submit a Pull request on GitHub.

More information

The VS Code documentation has a nice introduction to Git section with more useful tips.

The Quarto tutorial has more tips on using VS Code to edit Quarto pages.

Using the Visual editor

Visual editor
  • To use the visual editor right-click anywhere in the document you are working on, or use CTRL+SHIFT+F4

Formatting menu
  • You can now format text using a simple menu bar, instead of typing Markdown code.

Changing text in multiple locations

It happens from time to time that text that occurs in multiple locations needs to be changed. This can be the case when a URL to an external website changes; when this URL occurs in multiple places in the Research Support Handbook, it can be easier to change it in one go, rather than several times, separately. There are several ways to do this; the method below describes how to do it in the command line. One should use the Terminal (Mac and Linux users) or the Git Bash to follow this method.

Step 1: Cloning or pulling the handbook repository and navigating to the folder

If you don’t already have the Research Support Handbook cloned locally (see also above), you should clone the Research Support Handbook:

git clone git@github.com:ubvu/open-handbook.git

If you have the Research Support Handbook cloned locally but you want to make sure that you have the most up-to-date version, you should pull from the online (remote) repository:

git pull origin main This updates the main branch on your local repository.

Now navigate to the folder so you can start working in it:

cd open-handbook

Step 2: Making changes

Before you make any changes to the Research Support Handbook, make sure to open a new branch in which you can make your changes:

git branch url-replacement main
git switch url-replacement # Now you switch over to the new branch

This creates the branch url-replacement from the main branch. In principle, you can use any branch name you like as long as it’s descriptive and intuitive to understand for someone else and yourself.

Now you should find the occurrences of the old URL:

grep -rl old-url

grep is the command to find text in files. The option r is for recursive: the command then also looks into folders and subfolders. The option l prints the file names to the shell. old-url is the place where you should write the old URL.

This command will give you an overview of the occurrences of the old URL. The editors would recommend writing this overview to a new file so that you can check later on that all occurrences were updated. Make sure to save this file outside of the handbook folder/repository, otherwise this will be included when you push back to the remote repository. So, for example: grep -rl old-url > /your-folder-path/url-replacement.txt

In principle, you can choose any folder to save this file in and any file name. But make sure it makes sense so you can find it back easily. If you are not sure about navigating files and directories, you can find more information on the Carpentries website.

Now write the for loop:

for file in */*.qmd
do
sed -i 's/old-url/new-url/g' $file
done

The wildcard * makes sure that files in the nested directory ending in the .qmd file extension are looped. sed is a command that edits contents of files, the option -i ensures that changes are made in the existing file and no new file is created, s is for substitute, and g is for global (i.e. change each occurrence, not just the first one) (source).

Within both the old and new URLs, make sure to use a back slash, \, in front of every forward slash /. Otherwise the shell will interpret the first forward slash as the separator between the old and new URLs and it may throw you an error, or, worse, do something that you did not want to happen, and you may not notice.

Now check which files were edited by sed:

git diff --name-only

This will give you a list of files that were changed by the loop. This allows you to compare them with the list of files containing the old URL that you made earlier. If all files are included, you can add, commit and push to the remote repository (see below). If not all files were included, look closely at the file names that were not included. Usually this is the case for files that are in a parent or ‘grandchild’ directory. The wildcard */* may not work in the same way in all operating systems. In such a case, check what is the case and run the for loop again with *.qmd or with */*/*.qmd (this is explained in more detail in this conversation - in Dutch - between two of the editors). Now run git diff --name-only again to check that all files were included.

Step 3: Adding, committing and pushing

Now that you have ensured that all files have been updated as necessary, you should add the changed files to git:

git add -A The option -A ensures that all edited files are staged.

Now commit the staged files:

git commit -m "Updating outdated URLs" You can choose any appropriate commit message.

Finally, you need to push the new branch with the commit to the remote repository (on GitHub):

git push origin url-replacement This pushes your new branch url-replacement to the remote repository.

When you now log in to GitHub, you will see a notification that your new branch has new commits. You can press the button ’Compare and Pull Request` to open a Pull Request. From there, an editor will review your changes and merge the branch into the main branch.

Footnotes

  1. For Linux and Mac, this is usually called the terminal. For Windows machines, you would have to use the Git Bash↩︎