If you do a lot of edits please use a local build to preview and test.
- The homepage for the site is index.html.
- The guides are a Jekyll collection in the _content folder.
- Store assets in the same folder as the markdown file you need it in and include them by their filename. You can also use relative paths to re-use images from other guides.
- To link to another child guide, use the relative markdown path (e.g.
../devices/registration.md) and Jekyll will make it
- To link to another parent guide, use the relative markdown path (e.g.
../devices/index.md) or the directory path, ending with a slash (
- Guides are sorted on descending
titleascending and if those are equal
- Use blockquotes (
>) to create callouts for important notes.
- To set an image to use on Facebook and Twitter use
image:/absolute/path/to/image.pngin your frontmatter.
- You can use most of the icons we use in the console. Simply use
<i class="ion-eye"></i>in the Markdown and we'll style it as a button.
Build local for preview and design
$ gem install bundler
Install Jekyll using Bundler:
$ bundle install
Install Node.js and NPM.
Install front-end and development dependencies:
$ npm install
> This will also overwrite any local git pre-commit hook to execute [npm run webpack](package.json#L12), [npm test](package.json#L15) and [npm run add](package.json#L16) to append the webpack build.
Run Webpack, build the local Jekyll site and watch for changes:
$ npm run dev
Be aware that this will use Jekyll's experimental incremental mode. Only the file you edit will be regenerated. So a change in a guide's title will not cause the navigation on all other pages to be updated. Just kill the proces and run it again.
- Require and use any JS libraries you need in assets/js/_main.js and _page.js.
- Import any Sass files you need in assets/css/main.scss.
- Override Bootstrap variables in _sass/_variables.scss.
- Edit styles in _sass/_base.scss or break out to additional Sass files to keep it organized.
- Store layout assets in assets folder.
- Edit layouts in the _layouts folder.
- All layouts should inherit the default layout.
Build and upload a preview
If you do some major refactoring and would like to upload a build somewhere for preview, then you can use:
npm run scp user@host:/path
This will create a build in
_scp, upload it with
scp and then delete the directory. Make sure the server has your public key or it will prompt for a password and cause the script to fail.
Alternatively, you can set the
SCP_TARGET environment variable or dotenv.
Pull Requests and Pushes will be tested automatically by Travis. It will let Jekyll try to build the site and then run HTMLProofer to test for broken links etc.
The test will also run automatically before every commit. To run the test manually, follow Build local to install the dependencies and then run:
Some content we source directly from elsewhere, e.g. the MQTT API Reference.
Follow the previous section to install NPM and dependencies.
Run the pull script:
npm run pull
To source more content from elsewhere edit _scripts/pull.js.