Documentation for the balenaCloud platform. Join our forums to chat.
The intention of this repo is to provide our public-facing documentation. To view the documentation generated by this repo you should either run locally or view the hosted version.
To run the docs web application locally, you should do the following:
git clone https://github.com/balena-io/docs
cd docs
npm install
npm startAnd then open http://localhost:3000/docs.
Note: if you are using macOS and you get
"RangeError: Maximum call stack size exceeded"when runningnpm install(which eventually calls thebuild.shscript), have a look at the comments at the top of the'Dockerfile.bindmount'file.
- Issue Tracker: github.com/balena-io/docs/issues
- Source Code: github.com/balena-io/docs
If you think something is not documented, or can be improved, don't hesitate in sending a PR! Check CONTRIBUTING.md for the guidelines to ensure your PR can be merged as quickly as possible.
After a PR has been created, a member of the balena team will review and merge into staging.
Shortly after merging to staging it'll automatically be deployed to our staging environment (This should only take a few minutes).
Once deployed to staging, we will preview your changes. If everything looks good, a member of the balena team will make another PR from staging into the master branch. When this is merged, the changes will automatically deploy to production
For all, lower-case capitalization unless beginning a sentence (Ex. I like balena. Balena is great.)
- balena (used to refer to the company as a whole, not in place of balenaCloud, balenaOS or any other project)
- balenaEtcher
- balenaOS (note the capitalization of OS)
- balenaEngine
- balenaFin
- balenaCloud
- Notes/Warnings are formatted using CSS. Use the following syntax to make sure it's rendered correctly:
__Note:__
git clone https://github.com/balena-io/docs.git
cd docs
npm installNow to check that everything is working correctly, start the local server with:
npm start
You should now see the docs served from localhost:3000
To add you changes to the docs, create a new local branch of master:
git checkout -b my-docs-patch
Now you can make changes in this branch. Since our docs are static pages generated from markdown using metalsmith.io, each time you change some of the .md files you will need to run rebuild of the docs to generate the static pages. This is done by running:
./tools/prepare.sh
However there is a handy watch functionality that will watch for changes in /pages, /shared, and /templates and rebuild each time you save your changes. To use this, open a new tab in your terminal and run:
npm run watch-pages
Once you are happy with your changes, submit a pull request for you branch against master.
Note that you have to restart the development server if you edit other things like redirects.txt.
When creating new content or altering current pages, its recommended that you try keep things D.R.Y (Don’t Repeat Yourself). This is made easy by using “partials”. If you look in the /shared folder you will see a number of folders, these keep snippets or partials of the docs that can be reused all over the place. They also allow you to cleverly override a partial for a particular board type and language type. So in general you will see most of them just contain a _default.md which means that this partial will be used for all board and language types, but for partials like getDeviceOnDash we have device specific overrides.
├── getDeviceOnDash
│ ├── _default.md
│ ├── artik10.md
│ ├── artik5.md
│ ├── raspberrypi.md
│ ├── raspberrypi2.md
│ └── raspberrypi3.md
To use these partials in a markdown page all you need to do is add the following in the page:
{{ import “getDeviceOnDash” }}
and the engine will pull that partial into this location in the page.
To add additional external documentation follow these steps:
- Update
tools/fetch-external.shto add the additional external source. If required rename the source document as this will be used in the docs URL and in dynamically determining the "Improve this doc" link and must be unique. - Update
externalDocsinconfig/links.coffeeto add the link to edit the source file. This is the link presented in "Improve this doc". The key must match the name of the filename without the .md extension e.g."node-sdk": 'https://github.com/balena-io/balena-sdk/edit/master/DOCUMENTATION.md'for a file namednode-sdk.md. - In
config/index.coffeeadd the filename (again without the .md extension) to theEXTERNAL_DOCSvariable so that the system knows to correctly identify this file as coming from an external source. - If the source is currently duplicated in this repo then delete the content from this repo and add the file to
/.gitignore.
Its important to note that h1 and h2 headings will automatically be included in the left hand side navigation bar, so make sure to use these appropriately.
In the dynamically generated pages (the ones with the device-type and language dropdown) it is possible to use templates to dynamically change the device name and language name in your text. Here is an example:
Getting started with {{ $device_details.name }} using {{ $language_details.name }}
To add additional dynamic properties, see the files in /config/dictionaries.
If you remove a page that may be linked to externally to the docs, remember to add it to the redirects.txt in the root of the docs, if you don’t, then links will break and people will have a bad time, m’kay.
If you need to add image assets, add them to the /static/img folder, either under common if these images are general to all of the devices or resin, otherwise add them to the specific device folder.
The project is licensed under the Apache 2.0 license.