This website is created by Helmholtz HZI to support the open collaboration of researchers around RSV.
- RSV
- Get help
- Contributing content
- Information about the website
- Setting up your machine to make changes to the website
- Getting things set up locally
- Making changes to the website
- Add a researcher
- Infrastructure
- Making the site citeable
- Resources
For any issues with the site including typos or rendering issues, please file an issue or send a pull request. The site automatically deploys once pull requests are merged.
To contribute content, you can create a Pull Request with the content.
- Fork the repository (repo) of the serohub website.
- Draft your post in R Markdown or Markdown.
- (Optional) Preview and refine your post locally.
- Submit via pull request and preview your post.
- A SeroHub maintainer accepts your content, or requests changes.
An excellent place to learn about contributing science related blog posts is ropensci technical guidelines.
This website was built using Hugo.
Hugo is a website generator that pre-generates web pages so that they can be hosted very cheaply. It is used by a significant amount of the research and science communities due to its excellent support for markdown which enables researchers to use literate programming techniques in R and Python to interleave analysis and text.
This documentation assumes no prior knowledge with Hugo and will get you up and running with using it on your system. For content editing you will only need to concern yourself with four pages from the Hugo site:
We recommend taking the package manager approach if speed and ease-of-install is your priority.
For running a local version of the website so you can edit content in a controlled manner before pushing it up to the remote repository.
Front Matter in Hugo is metadata (data about your data) embedded within a content file. We can edit front matter values to specify, for example, a title and a publication date for a page.
Shortcodes are small snippets of HTML that can be added into a markdown content file. Hugo renders the shortcode using a predefined template. This website includes a sample content page which includes a custom shortcode created to fetch articles from the PubMed API. You'll be shown how to cutomise and reuse the shortcode for other content pages.
When you are working on content for the site, you will be working almost exclusively with markdown files (.md). Markdown is easy to learn and very well supported. Just remember, if there is content you want to change on the body of a page, there's a markdown file for it. There are some changes on the site you will need to make outside of markdown, which is discussed in the following section.
Before following the steps below, please ensure that the changes you make can't be done via Netlify CMS. The checklist below allows you to set up your machine to make more advanced changes to the site.
You need to be a member of the hzi-braunschweig organisation on GitHub to make changes to the site.
Here's our recommended checklist:
- Ensure you're a hzi-braunschweig GitHub member.
- Install Git Bash, instructions for Windows here.
- This process should also install Git on your system if it doesn't already exist. You should also confirm your Git identity is configured.
- Install Visual Studio Code here. It is recommended you restart your machine after install.
- As aforementioned, install Hugo. On Windows we recommend doing this using Chocolatey as the Hugo docs suggest.
- Ensure your terminal is navigated to the folder where you would like your local version of the codebase.
- Proceed to getting things set up locally to perform the Git clone and run Hugo webserver.
- Attempting a Git clone may prompt you for an SSH key, follow this video guide carefully to set up an SSH key. This validates that your machine is an authorised member of the organisation. Ensure that you generate your SSH key passphrase securely and store it in a safe place.
- Remember, cloning is just creating a local version of the codebase on your machine. So now you can view the repo folder in your computer's file explorer.
- Once authorised and cloned, you can open the repo using Visual Studio Code and run Hugo webserver. You will need an elementary knowledge of Git to commit and push your changes to the local repository. There are many resources online to learn from, including this guide on using Git with Visual Studio Code.
Optional steps:
- Learn the basics of bash terminal (you only need to know how to use the terminal to move between file directories).
- Improve your Visual Studio Code workflow by learning how to use shortcuts to navigate between files, learning how to use the search function to locate the field you want to change across files, and enabling autosave.
- If you're a member of the organisation,
git clone --recurse-submodules [email protected]:hzi-braunschweig/rsvhub.net.git - If you're not a member of the organisation, fork the repo, then
git clone --recurse-submodules [email protected]:<your account>/rsvhub.net.gitgit remote add upstream https://github.com/hzi-braunschweig/rsvhub.net.git
We use a theme hugo-infinite as the basis for the site. The --recurse-submodules argument in git clone will have established a connection. You should not make changes to contents in the submodule instead, you should copy files from the themes structure and paste them into the corresponding section of the main repository and edit it there. You only work with the submodule contents directly if you want to fix a bug and that is best done with a fresh fork of the theme directly from the theme's repository.
From inside the website directory, run hugo serve to get a live local copy (typically on http://localhost:1313) that will update whenever you make changes.
For changes to the website, there are a few key areas:
- The config file that supports changing many values used in the repository. Many of the values that you want to change are available either here or in .toml files found in the i18n folder.
For example, to change the value of the site name on the top left corner:
You would refer to the title value in config.toml. Use the search function in your IDE/Code editor to speed up the process of finding the value you'd like to change. The variable names are descriptive.
- index.html determines what the home page looks like. It may reference files in syntax like
{{ partial "leaflet.html" . }}-- these are sub-templates and are found in layouts/partials - baseof.html describes header and footer content used across the site. This is where you would change things like JavaScript files, the nav bar, and the footer
- share_study.md contains the html used to generate the contact form that will submit the contents to netlify. Note the Netlify free tier has an upload limit of 10Mb per month. This is not a long-term solution.
- hzi.css is the custom style sheet for the website. Use this to tweak or override the website appearance.
The user interface for adding and managing studies is built using the Netlify CMS.
The CMS is used to provide an interface to GitHub and Git activities behind the scenes. You can login with your Github account at rsvhub.net/admin. Please note,
- You need to use a github account that has NO access rights to the rsvhub.net repository. When you write a blog post ("General Content"), a study, or publication, it will create a fork of the repository in the users account and they can perform edits that will become pull requests for serohub maintainers to approve.
- If you are a maintainer or have any write access rights to rsvhub.net repository, you will end with an error
Failed to persist entry: API_ERROR: Not Foundwhen trying to save a new blog entry.
If you are editing content using the CMS the workflow is easy to follow from the Netlify guide.
Under participating studies and partners, the media is being imported through Netlify CMS within the uploads folder.
This is a custom shortcode to draw in articles from the PubMed database. You can specify which articles you'd like by entering your search term(s), a date range, and the number of articles to retrieve -- although you should be careful not to retrieve too many at once as it will make too many requests to the API.
This is a sample shortcode with the necessary parameters specified:
{{< fetchapi searchterm="influenza" articlesretrieved="2" mindate="2021/11" maxdate="2021/11" >}}Generating this output:
Remember that you simply place this shortcode within the markdown of whatever page you wish to add it to.
For search term, all special characters must be URL encoded. Spaces may be replaced by '+' signs.
Articles retrieved is the total number of articles from the PubMed input set to be retrieved, up to a maximum of 10,000
The two parameters (mindate, maxdate) must be used together to specify an arbitrary date range. The general date format is YYYY/MM/DD, and these variants are also allowed: YYYY, YYYY/MM.
You can find more information on using this API over on the PubMed documentation.
If you would like to add a researcher, the general content steps are taken but instead of generating files with markdown you amend the Researcher list.
The default site (en):
- The folder
content/publicationcontains the reference to scientific papers. It's our main folder to curate publications! - Each
.mdrefers to one scientific paper, and is named by its DOI, e.g.10.1101-2020.05.18.20103283.md - The markdown files are organized by the publisher, e.g.
content/publication/biorxiv/10.1101-2020.05.18.20103283.md
The language-specific sites (e.g. de):
- The majority of scientific papers are written in English language.
- In
config.tomleach language (excepten) has an additional content folder defined, e.g.contentDir="content_de"for the German site. - In order to display English papers, we will copy/mirror whole folders to the language-specific directory, e.g.
cp content/publication/biorxiv content_de/publication/biorxiv
We will host the solution on Netlify with the source files hosted on GitHub. This will enable HZI researchers to work in an open way and accept collaborations from others.
This website uses Hugo. To work with Hugo locally, you will need to install it.
If you are opening a local Hugo server for content editing you will only likely receive spacing and indentation errors within toml/yaml. Double check that you have enclosed your value in speech marks and closed it properly.
If you are venturing further into Hugo and making templating changes, the template debugging page and the Hugo Discourse are great resources.
"Studies" and "Publications" use custom section page templates, the rest use the default list and single templates.
"Contribute", "About" and "Test" are all menu items. From the front matter you can see that they are added to the top nav via Hugo's menu system.
The website is hosted on Netlify.
The CMS works using a principle called Open Authoring. You can see this configured in the CMS configuration here.
The website is automatically updated everytime there is a change to the master branch in GitHub. Additionally, any pull requests or branches will also have preview URLs built. The preview links for Pull Requests will be included in the Pull Request interface on GitHub.
The Netlify hosting has Visitor access > OAuth authentication enabled with a GitHub OAuth application - this is important for the Netlify CMS to support open authoring.
Below are the steps to configure authentication:
There are two steps to enable OAuth for the Netlify site.
-
In Github, click here to access developer settings for OAuth Apps and click the button to register a new application.
-
For the Authorization callback URL, enter
https://api.netlify.com/auth/done. Populate the other fields appropriately. -
On your new application's GitHub overview page, make note of the Client ID.
-
Generate a Client Secret and make note of it for later. You can't access this secret again.
When you complete application registration with GitHub, you need to add the Client ID and Client Secret to your Netlify site:
- Go to Site settings > Access control > OAuth.
- Under Authentication Providers, select Install Provider.
- Select GitHub and enter the Client ID and Client Secret from earlier, then save.
When you've configured GitHub as an authentication provider, you can use it to obtain an access token in your application. Check out demos to do this here.
Netlify can support custom SSL certificates to be associated with the intended domain of rsvhub.net The SSL can either be a letsencrypt managed certificate or it can support a wildcard domain SSL. Note that the custom certificate route requires the SSL certificate to be updated manually, whenever a new one is issued.
To make open-source code citeable we can assign it a DOI. This is essentially a way of presenting the entire repo as a scholarly work available for citation. Our recommended way to do this is to link the GitHub repository to Zenodo.
A video guide on this process or carry on reading:
- Visit https://zenodo.org/ and select the Log In with Github option.
- Enter Github credentials and authorize Zenodo to access repositories.
- Once in the account, click on the dropdown menu next to the account name on the top-right and select 'GitHub'.
- Make sure the repo you want to make citeable is public and flip the switch to make it a Zenodo-enabled repo. This means you allow Zenodo to create a DOI for this repo.
- This is a good time to ensure your repo includes an appropriate license so that others know your sharing conditions.
- On Github, create a release for the repo with a tag version, target branch, release title and release description.
- After publishing the release, go back to Zenodo and hit "Sync" so that it processes the latest changes.
- The repo is now enabled and Zenodo has generated a badge for it. Clicking the badge opens a modal with code in different programming languages for embedding into your project.
- On Zenodo, click on the repo name and then the DOI link to access its metadata. You can then edit this if you'd like.
- Git
- Hugo
- Hugo Quickstart
- In repo: Intro to (Hu)go templates and Writing Markdown
- Intro to markdown
- Maëlle Salmon, ROpenSci blog posts
- Netlify
- Blogdown