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

   cd <path>

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

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

3. Install dependencies

   yarn

4. Run the Gatsby development server

   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'.

   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:

   ![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:

```cpp
#include <iostream>
int main() {
    std::cout << "Hello, World!";
    return 0;
}
```

Maths Symbols and Equations

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

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

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

  $$
  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.

```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:

```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 a caption:

<Grid columns='1fr 1fr' rows="1fr 1fr" 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.

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:

<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:

<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:

<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>

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:

  ---
  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
  ---

• 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 /
  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 master, it is automatically deployed to the main site.