A Git-Building project can be as simple as a folder with some Markdown files in it. To add extra information into these files to allow a bill of materials to be generated we use a syntax we call BuildUp. Git-Building will then process the BuildUp and export the result it in either a plain Markdown format or HTML.

When specifying parts in BuildUp they can have their own BuildUp page, or can be part of a BuildUp part library in YAML format.

It is possible to customise how Git-Building builds the Buildup into plain markdown or HTML by making a configuration file called buildconf.yaml.

GitBuilding can also be used to generate more complex documentation for multiple similar projects. For more information see our organising complex projects guide.

Table of contents

BuildUp Syntax

Page title

BuildUp may use a page’s title in another page. A pages title is the first instance of a H1 (Heading Level 1) markdown title using the # syntax.

To link to another file and have it included in as a step you append {step} to the link for example


[Print the components](print.md){step}

or in reference style:


[Print the components]{step}
[Print the components]: print.md

If you want to use the title of the page as the link text then you can replace the link text with a ., so


[.](print.md){step}

will also give the same result if the title of print.md is “Print the components”. This is not implemented for reference style links as there is nothing to reference.

Note that {step} is case insensitive, {Step} or {STEP} are also valid.

To have a part counted in the bill of materials a part link is used. A part link is a link followed by the syntax {Qty: quantity} where quantity can be a number of free text. The following are valid part links:


[screws]{Qty: 4}
[bigger screws](bigscrews.md){qty:Many}

Just as with the step links qty is case insensitive, also the space after the : is optional.

Multiple links to the same item will be counted. Only the first one needs to have the link (URI) specified as the final markdown will create a reference style link for all parts. Linking to the same item using different text can be achieved using [markdown] reference link syntax:


Screw an [M3 nut](m3nut.md){Qty: 1} onto the [M3x25 screw][m3x25screw.md]{Qty: 1}. Then add[a second nut][M3 nut]{Qty: 1} to lock it in place.

This will count two M3 Nuts and one M3x25 screw.

Numbers are counted as expected. If text quantities are added the result is Some, and a warning is logged. GitBuilding is somewhat unit aware. It can add 10 g and 45 g to get 55 g, it can also add 1 kg and 200 g to 1.2 kg. The unit system is somewhat limited and could do with expanding. However, if you add unknown units it will work as expected if they are consistent, i.e. 2 splashes and 3 splashes will add correctly to 5 splashes.

The part link (URI) can be a link to anything for example another website, a markdown file, or an STL file. To use link to a file in a part library you should specify it in the form


[Part](library.yaml#key){Qty: 1}

where library.yaml is the library file, and key is the key for that part.

Extra part metadata

You add extra metadata to a part link to, for example, categorise the part. This information can either be added inside {}s for links or a reference-style link can be used. To use a reference style link extra information can be added inside {}s in the alt-text.

The following are equivalent:


Use a [Large screwdriver](screwdriver.md){Qty: 1, Cat: Tool, Note: 'A Pozidriv works best, but you could try a Philips.'}.

and


Use a [Large screwdriver]{Qty: 1}.

[Large screwdriver]: screwdriver.md "{Cat: Tool, Note: 'A Pozidriv works best, but you could try a Philips.'}"

Extra information is specified in key value syntax that is case insensitive, a comma is used before a new key. The following keys are defined:

  • TotalQty - This sets the total of a part used on a page. It can be use to over-ride the counted value. It can also be used to check all uses are mentioned in the text as GitBuilding will produce a warning if they don’t match.
  • Cat - Short for “category”. This defines the type of part. Standard BuildUp has two categories Part and Tool. Parts are counted normally, for tools the maximum quantity used in a single link is used for the bill of materials. GitBuilding can define custom categories in its configuration.
  • Note - This sets a note which is displayed with the part in the bill of materials.

Sometimes a part that is used in one step of the documentation was created in a previous step. This is handled by using output links and from step links.

Creating an output

Output links define a part that has been created by putting output in the part-link information, for a link with no target:


You have now successfully built the [z-actuator]{output, Qty:1}. You will need this later.

The output will actually create an anchor point not a link. We have chosen this syntax because there is no standard markdown syntax for an anchor point.

Using an output

To use a part defined in a previous step you must use the same part name as the output, but set the link target to fromstep. For example:


Now attach the [z-actuator](fromstep){Qty:1} that you made earlier.

This will add the part to the bill of materials for this page. The part will not end up in the total bill of materials for the project as it was made by an earlier step.

Displaying Bill of Materials

To display a pages bill of materials in the markdown the use {{BOM}}. {{BOM}} will be replaced in the output with the bill of materials.

For pages with a larger bill of materials it make sense to have it on a separate page. To generate the page, [linktext]{BOM}. generates a bill of materials page and creates a link to it. It will also create a CSV file for the bill of materials, and link to this too.

This bill of materials can be found [here](BOM)

Page steps

Each buildup page can be divided into steps. To do this make an H2 level heading by starting a line with ## You can then append {pagestep} to the line. This serves two purposes, it gives you a sub-heading ID you can refer to in a link, and it also auto numbers the steps. For example


## Open the tin {pagestep}
Get the tin and open it with a screw driver.

## Apply paint {pagestep}
Apply paint to the wall

would render as

Step 1: Open the tin

Get the tin and open it with a screw driver.

Step 2: Apply paint

Apply paint to the wall

You can then link to this step with page.md#open-the-tin. The id for the heading link is contains only the alphanumeric characters in the heading plus - and _. Spaces are changed to -s and all letters int the id are lower case.

You can also redefine the ID, if you replaced the line above with:


## Open the tin {pagestep: tin}

then you could link to the step with page.md#tin.

Embed and preview

GitBuilding can embed previews of 3D models, PDFs and YouTube videos. Preview uses the same syntax as images for example:


![](gear_screw.glb)

![](https://www.youtube.com/watch?v=OEVybXS-9k4)

Supported files/links are:

  • Youtube video link in the full link format (as above)
  • STL files
  • WRL files
  • GLB/glTF files (Will attempt to turn an animation into a exploded view slider)
  • PDF files

All files can be dragged and dropped into the editor (links cannot):

3D preview pages

The above supported 3D models can be previewed on their own page. Any STL linked to as a part link will link to the preview page automatically (WRL and GLB/glTF do not).

You can also force a link to create (and link to) a preview page with the following syntax:


Now print [Thingy.stl](models/thingy.stl){previewpage}

Note that {previewpage} can only be used on a link with no other meta data, not as part of a part link or other type of link.

Page part data

Any page in BuildUp can be linked to as a part, this allows a longer, more complex explanation of a part than you would want to write into a library file. However, you may wish to provide the same information such as supplier information or specifications. This allows this information to propagate through to the Bill of Materials, and to be rendered the same as it would be for a page created from a part library. This part data be added with a YAML header in your build up page.

The YAML header must be the first thing in the build up file. It consists of YAML data between lines that contain ---. To define this part data use the YMAL key PartData, the value of this key should use the same syntax as an item in a library file, except that Name and Description will be ignored. An example is:


---
PartData:
    Specs:
        Material: A2 (18-8) Stainless Steel
    Suppliers:
        McMasterCarr:
            PartNo: 91292A112
            Link: 'https://www.mcmaster.com/91292A112'
        RS Components:
            PartNo: 280-997
            Link: 'https://uk.rs-online.com/web/p/socket-screws/0280997/'
---

# M3 x 8 mm Cap Screw (Stainless Steel)

This is a longer page all about this rather simple metric screw. I could provide photos of the screw, technical drawings, or references to the ISO standards that define the thread.


GitBuilding BuildUp

While GitBuilding is currently the only project using BuildUp we want to make BuildUp into a standard. Long term we would like platforms like Wikifactory, Wevolver, and Instructables to support the standard. This way if your documentation is portable.

GitBuilding does a few things which can make documentation more useful, but we don’t think they belong directly in the BuildUp standard as other software or platforms will want to work differently. None of the what is detailed bellow changes the BuildUp standard, or adds any extra syntax, instead a certain way of writing BuildUp will cause GitBuilding to tidy up the documentation.

Image galleries

Sometimes a large group of sequential images looks messy. In GitBuilding if you start a new line and the include multiple images on that same line or subsequent lines (with no other text on the lines) it will turn the images into a gallery. For example:


Start screwing the gear into the actuator column from the top. Apply a small amount of [light oil]{Qty: "A few drops of"} to the screw thread, before you fully tighten the screw
![](images/3-5-GearAttach.jpg)
![](images/3-6-Oil.jpg)
![](images/3-7-GearAttach.jpg)

will render as:

Start screwing the gear into the actuator column from the top. Apply a small amount of light oil to the screw thread, before you fully tighten the screw

Equations

GitBuilding uses KaTeX and markdown-katex to render LaTeX equations:


We can render inline maths with: $`a_i`$ and full equations as:

```math
A = \sum_{i=0}^{N}a_i
```

which will render as: