README.md

The Things Network Documentation

This is a Jekyll site configured to be build and served through GitHub Pages.

Update content

Because we let GitHub Pages do the Jekyll builds the website will be updated automatically after pushing commits or merging pull requests.

Guidance

• The homepage for the site is index.html.
• The guides are a Jekyll collection in the _guides folder.
• To archive (or draft) a guide move it to _versions/*/.
• Use the main file of each guide for the intro.
• Use the sections front matter to include additional content from files relative to the guide, preferably in a subfolder with the same name. Make sure to start these files with _ to prevent Jekyll for outputting them as stand-alone pages.
• Store guide assets in the same folder as the markdown you need it in and include them by their filename. You can also use relative paths to re-use images from other guides.
• The /docs baseurl will be prepended to any links and image sources that start with /.
• Always end internal links with /.
• Use blockquotes (>) to create callouts for important notes.
• If you do a lot of edits please use a local build to preview and test.

Build local for preview and design

1. Install Ruby 2.0.0 or higher

2. Install Bundler:

   $ gem install bundler

3. Install Jekyll using Bundler:

   $ bundle install

4. Install Node.js and NPM.

5. Install front-end and development dependencies:

$ npm install

4. Run Webpack, build the local Jekyll site and watch for changes:

   $ npm run dev

NOTE: Running npm install will overwrite the git pre-commit hook to execute npm run webpack, npm test and npm run add to append the webpack build.

Guidance

• Require and use any JS libraries you need in _app/main.js.
• Import any Sass files you need in 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.

Test

Pull Requests and Pushes will be tested automatically by Travis using the test script. This will use markdown-spellcheck on the Markdown source files, let Jekyll try to build the site and then use HTMLProofer to test for broken links etc.

To run the test local, follow Build local to install the dependencies and then run:

./test

The test will also run automatically before every commit.

To ignore spelling errors for all or certain files, add them to .spelling.

Automatic updates

Some content we source directly from elsewhere, e.g. the MQTT API Reference.

Update

1. Follow the previous section to install NPM and dependencies.

2. Install Gulp:

   sudo npm i --global gulp

3. Run the pull task:

   gulp pull

Source

To source more content from elsewhere edit gulpfile.js.