NUbook

NUbook is the handbook and high-level documentation for the NUbots team. What you are looking at right now is NUbook! This page has information on how NUbook works.

Getting Started

Install Prerequisites

You'll need Git, Node.js and Yarn installed. See below for operating system specific instructions.

Install NUbook

1. Navigate to the directory where you want to install NUbook

   Copy
   cd <path>

2. Clone the NUbook repository and cd into the cloned directory

   Copy
   git clone https://github.com/NUbots/NUbook.git
   cd NUbook

3. Install dependencies

   Copy
   yarn

4. Run the Gatsby development server

   Copy
   yarn dev

5. Preview the site by visiting localhost:8000 in a browser

Contributing Content

All additions and edits are done through GitHub pull requests. To add or edit content

1. Clone the repo, install dependencies, and run the development server as shown in the Getting Started section above.

2. Create a new branch for your changes, in the format your_surname/short_description_of_change. An example is below for someone with the surname 'paye'.

   Copy
   git checkout -b paye/add_2019_debrief

3. Make your changes by adding or editing MDX files in src/book/. See below for how to write and organise pages.

4. Preview your changes by visiting localhost:8000 in a browser.

5. Commit and push your changes to GitHub.

6. Go to the repo on GitHub and create a pull request for your branch. Your pull request will be reviewed, merged, and deployed to the live site.

More information on using Git can be found on the Git Guide.

NUbook content should be accessible and inclusive. A guide on making content accessible and inclusive can be found on the Australian Government website.

Writing Markdown

NUbook content is written using MDX, an extension of Markdown with support for dynamic content via JSX and React components. Markdown provides a minimal syntax for writing and styling text content.

GitHub has a good guide for getting started with Markdown. There's also a short video series on using Markdown.

NUbook has a kitchen sink demonstrating the various functionalities avaliable to use when writing NUbook pages.

Images

To add images to a NUbook page

1. Add the image file in an images folder in the same directory as the file being edited

2. Reference the image in Markdown:

   Copy
   ![Image description for search engines and screen readers](./images/image.png 'Image caption')

The image caption will be displayed below the image and is an optional component.

The image description should present the content and function of the image. Find guides on writing good alternative text at WebAIM.

Syntax-Highlighted Code Blocks

Use triple backticks ``` on separate lines to open and close code blocks. Specify the language with a file extension after the opening backticks for syntax highlighting.

Example C++ code block:

Copy
```cpp
#include <iostream>

int main() {
    std::cout << "Hello, World!";
    return 0;
}
```

Maths Symbols and Equations

• For inline math, wrap TeX-formatted content with a $:

  Copy
  The equation is $c^2 = a^2 + b^2$.

• For math blocks, wrap with $$ on separate lines:

  Copy
  $$
  e^{i\phi} = \cos(\phi) + i\sin(\phi)
  $$

NUbook uses KaTeX to render math. See the KaTeX support table for supported symbols and functions.

Graphviz graphs

NUbook includes Graphviz, which you can use to draw graphs by writing specially-formatted code blocks in Markdown.

To create a graph, use triple backticks ``` on separate lines to open and close the graph, then specify the Graphviz layout algorithm after the opening backticks, followed by the source code for the graph.

For example, the following code block in Markdown creates a directed graph with three connected nodes using the dot layout algorithm.

Copy
```dot
digraph {
  A -> B -> C
}
```

When rendered in NUbook, it produces the following graph:

The available layouts you can use are:

• circo
• dot
• fdp
• neato
• osage
• patchwork
• twopi

You can view examples of each of these layouts in the kitchen sink.

Graph Captions and Alternative Text

Just like with images, you can add captions and alternative text to describe graphs. You do so by using comments in the graph source. The first line of comment at the start of the graph will be used as the caption, and subsequent lines of comment will be used as alternative text.

For example, the following source:

Copy
```circo
# The connections between modules A, B, and C
# A directed graph showing node A connected to node B, which is connected to node C
digraph {
  A -> B -> C
}
```

Produces the following graph with the appropriate caption and alternative text:

Learning Graphviz

Here are some resources for learning how to draw graphs with Graphviz:

• Graphviz Pocket Reference
• Drawing Graphs using Dot and Graphviz
• Graphviz Tutorial
• Drawing graphs with dot

Content in Grids

You can show content such as images, code, and math equations side-by-side in a grid.

The following example shows four images in a 2x2 grid with large spacing between items and a caption:

Copy
<Grid columns='1fr 1fr' rows="1fr 1fr" gap="large" caption="Some lovely pets">

![Bird](https://source.unsplash.com/featured/1600x900/?bird,1 'Bird')
![Cat](https://source.unsplash.com/featured/1600x900/?cat,1 'Cat')
![Dog](https://source.unsplash.com/featured/1600x900/?dog,1 'Dog')
![Turtle](https://source.unsplash.com/featured/1600x900/?turtle,1 'Turtle')

</Grid>

The columns and rows are specified using CSS grid syntax. fr is a fractional unit that specifies a fraction of the total available space (width for columns, and height for rows). columns='1fr 1fr' creates two columns of equal width, while rows='1fr 1fr' creates two rows of equal height.

The gap property sets the spacing between items in the grid, and can be one of none (no gap), small (the default), medium, large, or extra-large.

Images in Tabs

You can show multiple images in the same place by putting them in tabs. The caption of each image is used for its tab button label.

The following example shows four images in tabs:

Copy
<TabbedImages>

![Bird](https://source.unsplash.com/featured/1600x900/?bird,1 'Bird')
![Cat](https://source.unsplash.com/featured/1600x900/?cat,1 'Cat')
![Dog](https://source.unsplash.com/featured/1600x900/?dog,1 'Dog')
![Turtle](https://source.unsplash.com/featured/1600x900/?turtle,1 'Turtle')

</TabbedImages>

Alerts and Warnings

You can show an informational alert using:

Copy
<Alert>

Did you know you can lorem ipsum dolor sit amet, consectetur adipisicing elit.
Autem quo deserunt amet suscipit, fuga ullam cumque accusamus doloremque rem
qui?

</Alert>

You can also show a warning using:

Copy
<Alert type='warning'>

Be careful not to lorem ipsum dolor sit amet, consectetur adipisicing elit.
Autem quo deserunt amet suscipit, fuga ullam cumque accusamus doloremque rem
qui.

</Alert>

Bibtex Referencing

NUbook supports Bibtex referencing in Markdown. You can use it as follows.

1. First, add the Bibtex file containing your references to the same folder that contains the MDX file you're editing. Give the Bibtex file the same name as the MDX file, but with a .bib extension. For example, if you're editing 01-introduction.mdx, the Bibtex file should be 01-introduction.bib.

   If you need to reference a Bibtex file from multiple MDX files

   You can use the references key at the top of the MDX file to override the default Bibtex file path.

   Copy
   ---
   title: My page
   # ... other data
   references: ./shared-references.bib # Relative path to the shared references file
   ---

2. In the Markdown file, add in-text citations using <cite> tags. For example, if there's a citation in the Bibtex file with id smith2018, you can reference it in the Markdown file like so:

   Copy
   Fuga ullam cumque accusamus doloremque rem <cite>smith2019</cite>.

   This will add an inline citation with an auto generated citation number, linked to the full citation reference in the list of references.

   You can add multiple in-text citations in the same place by including multiple comma-separated ids in the <cite> tag. For example, if there's a citation in the Bibtex file with id smith2018 and a citation with id brown2005, you can reference both as follows:

   Copy
   Fuga ullam cumque accusamus doloremque rem <cite>smith2019,brown2005</cite>.

3. After adding your in-text citations, create a new section at the bottom of the MDX page to show the list of references:

   Copy
   ## References
   
   <References />

See the Referencing kitchen sink for an example of referencing.

Organising Pages

Pages are written in MDX files and stored in section and chapter folders in the src/book/ directory, and organised as follows:

• Each page's filename is numbered to create the order that will be used for menus and the previous/next page navigation links.

• Each page has "frontmatter" at the top of the file specifying details such as title and description:

  Copy
  ---
  section: The NUbots Team
  chapter: Introduction
  title: Introduction to NUbots
  description: Learn about what we do, key people, and where to find the lab.
  slug: /team/introduction
  authors:
    - Josephus Paye II (@JosephusPaye)
    - Ysobel Sims (@ysims)
    - Lachlan Court (@LachlanCourt)
  ---

• The frontmatter is written in YAML, with the following supported fields:

  Field	Type	Presence	Description
  section	String	Required	The section the page will appear under in the sidebar menu (case sensitive)
  chapter	String	Required	The chapter the page will appear under in the sidebar menu (case sensitive)
  title	String	Required	The page title
  description	String	Required	A short, one-sentence description of the page content
  slug	String	Required	The page URL relative to the root of the site, starting with /
  authors	List	Required	A list of authors of the page, in the format Name (@GitHubUsername), or just Name. Authors without a username will have the NUbots icon as a default avatar, without a link to GitHub.
  references	String	Optional	Relative path to a .bib file with references for use on the page. Defaults to [mdx-file-name].bib if a matching Bibtex file with the same name as the MDX file is available.
  keywords	List	Optional	Keywords for the page content, used for SEO
  hidden	Boolean	Optional	When true, removes the page from menus and disables search indexing

Formatting Code

All code in NUbook (including Markdown) is formatted using Prettier for a consistent style.

This style will be checked automatically when you push code to the repo. If there are any issues, the push will be aborted with an error message listing the files that have issues.

If you need to, you can:

• check formatting by running yarn format:check.
• automatically fix formatting issues by running yarn format.

Deploys and PR Reviews

Pull requests are automatically deployed as previews using Netlify, which will run code quality checks and report failures before a deploy.

The preview URL is of the form https://deploy-preview-[PR number]--nubook.netlify.com/ where [PR number] is the pull request number. For example, https://deploy-preview-21--nubook.netlify.com/ is the preview URL for pull request number 21.

You can get this URL from the Details link of the netlify/nubook/deploy-preview check at the bottom of the PR page:

We recommend that you add this URL to your pull request description after the first deploy. This makes it easier for reviewers to see your changes rendered without having to clone and build the PR locally.

When a pull request is merged into main, it is automatically deployed to the main site.

Building for production

The yarn build command is used to build the site into a set of static HTML, CSS, and JS files that can be deployed to any webserver. This command is run automatically by Netlify when a change is merged into main.

Running yarn build locally can be useful to preview the site exactly as it will be in production, or to debug an issue that occurs only in production. To use it:

• Run yarn build to build the site and optimise assets. The resulting output will be placed in public/.
• Run npx http-server public/ to start a simple webserver in the public folder. This will print a URL you can open in your browser to preview the built site.