3e4c20fa0f
* docs(markdown): Allow adding CSS classes directly to Markdown
* docs(markdown): Document the {my-class} syntax in the README
188 lines
6.3 KiB
Markdown
188 lines
6.3 KiB
Markdown
# 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.
|
|
|
|
```markdown
|
|
This is my paragraph. {p-2}
|
|
|
|
 {mt-2}
|
|
```
|
|
|
|
```html
|
|
<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:
|
|
|
|
```json
|
|
// 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._
|