This is the source for docs.atsgarage.com and for the HERE Developer Portal docs for HERE OTA Connect. It’s built with Jekyll, a static site generator.

The text is written in Asciidoc, and rendered by Asciidoctor. Asciidoctor exercises a large number of styles, and has a tool to build stylesheets called asciidoctor-stylesheet-factory. However, that’s pretty much just a compass pipeline, so we added it to our jekyll build process (to eliminate some annoying steps). See ` _compass` for all those details.

Building the site requires a github access token with access to ATS private repos. Pushing the site to docs.atsgargae.com requires a set of AWS IAM credentials with access to the docs.ota.here.com S3 bucket. Pushing to the dev portal requires push access to https://gerrit.it.here.com/#/admin/projects/DOCS/ota_update_platform.

Build the site with Docker:

Build the site from a local jekyll install:

Publish to the web:

Publish HTML assets to the internal HERE docs repo:

If you’re having issues with how jekyll is rendering the site, you can add debug breakpoints to any of the layouts or includes with a {% debug %} liquid tag. See the debugger docs at https://github.com/octopress/debugger.

If it’s a problem that only affects a single page, you can set the layout of that page to 'debug'.

The sidebar navigation can be customized in ` _config.yml`. The sections key lists the sections that will appear in the navigation, and the navigation_tabs key lists the tabs, and which sections each one contains. (Details in the yaml comments.)

You can make codetabs appear by using asciidoc attributes. Just put multiple source blocks, give one of them the "primary" role, and the others "secondary". Make sure to give each block a name; that’s what will be used for the title of the tab. Example:

The web app needs some contextual help pages. Since that’s documentation, we want to keep the single source of truth here in the docs repo. We accomplish this by writing the contextual help pages in asciidoc (using include::[] statements as liberally as possible). For each contextual help page, do the following:

1. Create a new jekyll page with the category context_help:

   ./bin/jekyll-page "My page title" context_help

2. Change the :page_layout: to context_help to make it render as raw HTML without the navigation, etc.

3. Write your doc.

4. It will render in the static site under /context_help/page-name-slug.html when the site is built.