GBADsInformatics/Docs

Our documentation site deployed with AWS Fargate

Documentation Server

🦖 💻 🌐 🐮 🤒

Welcome to the GBADs documentation server github repo!

Table of Contents

1. Installation
2. How to configure the site locally
   • 2.1. Modifying different parts of the site
   • 2.2. Creating a term
3. Wiki documentation
   • 3.1. How do I order my files?
   • 3.2. Ordering folders sidebar positions
   • 3.3. How do I add multiple authours to a blog post?
   • 3.4. Where can I learn more about styling?
   • 3.5. How can I translate the site to another language?
4. Developers' message

1. Installation

1. Clone the repo with git clone https://github.com/GBADsInformatics/Docs.git
2. Change the current directory to the cloned repo with: cd Docs
3. Download dependencies with:
   1. npm i
   2. npm run packs
4. Make changes...
5. Push changes to the "master" branch, and the site will update!

2. How to configure the site locally

In the cloned repo with the installed dependencies, do the following:

1. Run the code with:npm run dev
2. Client runs on http://localhost:3000/.

2.1. Modifying different parts of the site

All of the files that modify the main site are in the client folder.

What do you want to modify?	Where is it?
Homepage	/client/src/pages or /client/src/components
Site defaults (general info. Footers, titles, etc)	docusarus.config.js
Documentation (Place markdown files here)	/client/docs
Blogs (Place markdown files here)	/client/blog

2.2. Creating a term

To create a term in documentation, follow these steps:

• Create the markdown for the term page and place it in the /client/docs/terms folder. Example:
• Next, in your documentation file placed in the /client/docs folder, swap for your term with the following syntax: %%term_text|term_name%% Example: To display the term 'Party' use the corresponding ID associated with it. In this case, the corresponding ID is 'partyTerm'.
• Then, run the yarn docusaurus parse command, and check your documentation file and terminal to see if there are any errors.
• Finally, run the yarn docusaurus glossary to update the glossary.

3. Wiki documentation

3.1. How do I order my files?

By giving your files a naming convention like this:

• 01-introduction.md
• 02-details.md
• 03-conclusion.md

You can easily order files.

Also, by placing something like this:

---
sidebar_position: 6
---

At the top of your markdown file, you can order where your document goes.

3.2. Ordering folders sidebar positions

By including a category.json file in your folder and placing code like this:

{
  "label": "Tutorial - Extras",
  "position": 3
}

You can order where your folder shows up on the sidebar.

3.3. How do I add multiple authours to a blog post?

This is a pretty easy fix. In the header of the markdown document, modify the "authors" property to have a list of id's instead of a single id.

Example:

3.4. Where can I learn more about styling?

The Docusaurus documentation site has lots of info about styling. Most documentation material regarding the frontend is found on the Docusaurus page.

3.5. How can I translate the site to another language?

Using the Translate Docusaurus repo created by Flex Consulting Solutions, developers can easily translate the site into any chosen ISO language.

4. Developers' message

Feel free to contribute to this repo by sharing your thoughts and ideas, raising issues (if found) and providing bug-fixes. For any information or support, please do not hesitate to contact us through this Github repository or by email.

Developed by Matthew Szurkowski.