docsearch/docs

Documentation website

This subdirectory holds the documentation website content as well as scripts to generate it.

Main commands

Building the website

You can build a new version of the website by running yarn run build in this directory or yarn run docs:build at the repository root.

It will read all source files in ./src and build the final static website in ./dist.

Local development

You can run a local copy of the documentation website by running yarn run serve. This is an alias for running yarn run docs:serve at the repository root.

This will build the website in ./dist and expose it on localhost, along with live-reload.

Deploying the website manually

You can deploy the website manually by running yarn run deploy in this directory or yarn run docs:deploy at the repository root.

This will build the website and then commit the content of the ./dist folder to the gh-pages branch and push it to GitHub.

Auto-deploying

Any new commit on master that modifies the ./docs folder will automatically trigger a build and deploy it.

It works by having Netlify listen to any new commit on master and running ./scripts/netlify-master in response (see netlify.toml for details). Note that the website is not hosted on Netlify, but on GitHub Pages (more on that later).

The script compares the date of the last commit in ./docs with the date of the last deploy. If no new commits were added, it will stop. Otherwise, it will continue and build the website.

To make this comparison, both this script and the manual deploy script add a last_update file to the ./dist folder containing the timestamp of the last deploy. This file is then used to see if changes are present and should be deployed.

Once the build is complete, the ./dist folder is committed to the gh-pages branch and pushed to GitHub. This part requires some non-trivial git and ssh configuration commands to push data from Netlify to GitHub pages on our behalf (check ./scripts/netlify-master for more details).

Deploy previews

Any new Pull Request to the documentation will trigger a deploy preview build.

Netlify is configured to run ./scripts/netlify-deploy-preview on each new PR (check netlify.toml for details).

This script will first check if changes were made to the ./docs subfolder in the PR. If no change were made, the preview will not be generated (this will make processing time faster).

Whenever the preview is ready, a message from Algobot will be added to the PR, along with the link to the preview. This is configured in Netlify UI in Build and Deploy > Deploy notifications > Comment on GitHub pull request when deploy succeeds. It uses a GitHub token from Algobot to post on its behalf. To generate such a token, login to Netlify with Algobot and pretend to create such a notification on any project, generate a token, and then copy-paste it in the real DocSearch account in Netlify.

Internals

The documentation generation is not using any existing static websites generators, but custom JavaScript scripts.

The main two entry points are ./scripts/build.js and ./scripts/serve.js. The second one adds a webserver with live-reload on top of the first one.

HTML

All Markdown files situated in ./src will be transformed into .html files in ./dist. They will be wrapped into the layout defined in their front-matter.

All the headers will be converted to their respective <hX> tag, along with a unique #id to allow for easy anchoring.

You can use plain HTML inside those Markdown files if you need more advanced styling. The custom {my-class} syntax is also possible if to add CSS classes to elements.

This is my paragraph. {p-2}

![Pretty image](./img.jpg) {mt-2}

<p class="p-2">This is my paragraph</p>

<p class="mt-2">
  <img src="./img.jpg" alt="Pretty image" />
</p>

Layouts

All layouts are saved in the ./src/_layouts folder.

All config options defined into config.json are passed to the layouts and can be used there.

You can also use mixins or include other files from the layouts.

Note that the current layout logic is simple and might not handle complex recursive cases, but should be enough for simple cases.

CSS

CSS is processed through PostCSS. It expects an entry file in ./src/style.css.

We are using postcss-import, allowing you to @import files from the ./src/_styles/ directory to better split your CSS code in logical chunks.

Most of the styling based on tailwind.css, with the config file behing tailwind.config.js. It contains default sizing and coloring to follow the Algolia brand guidelines.

The final CSS files is then compressed through PurgeCSS (to keep CSS classes that are actually used) and CleanCSS (to minify it).

JavaScript

JavaScript code is processed through Babel. It will compile all files situated in ./src/js.

Note that it compiles JS, and does not bundle it. We might add Webpack/Parcel support later.

Assets

Any file with the following extensions found in the ./src folder will be automatically copied to the ./dist folder with the same folder structure: gif, jpg, png, ico, html, svg and woff.

Placeholders

Values defined in the placeholders key of the config.json file can be used in JavaScript and Markdown files by using the {{key}} syntax.

For example if you have:

// config.json
{
  "placeholders": {
    "projectVersion": "1.4.2"
  }
}

Every occurrence of {{projectVersion}} in any .md or .js file will be replaced with 1.4.2.

Sidebar

The left sidebar of the documentation is generated based on the sidebar key of the config.json. The key should contain an array where each key is a part of the sidebar, with a title and a list of pages. Each of those pages in turn is an object with a title and url value.

The layout will then automatically create all the links and color the active page. Subsections inside the current page will also be added for every h2 element extracted from the markup of the current page.

Redirects

The config.json file can hold a redirects array, with object containing both a from and a to key. For each from, it will create a plain HTML page at this location, that will redirect anyone visiting it to the page defined in to.

Note that both those links must be defined as relative to the site.url value.