Uses Docusaurus.
First, clone & enter the repo directory:
git clone [email protected]:questdb/documentation.git
cd documentationNext, install dependencies:
yarn
yarn start
This command starts a local development server and open up a browser window.
Most changes are reflected live without having to restart the server.
You'll need to sign a quick CLA.
Pretty standard, check it out.
This is done on PR creation.
First create a new branch.
Locally, ensure your changes look good.
Then push your branch to GitHub and create a PR.
We'll review the PR and generate a preview build.
A QuestDB member must add the preview label to your PR to deploy a preview build.
Once it looks good, we'll merge!
We'd love your help!
Raise a GH issue or tackle a PR.
Our SQL syntax diagrams are created using Railroad.
To create a diagram, use the Railroad online editor to see it rendered.
Once you're happy with it, copy the Railroad syntax and add it to:
static/images/docs/diagrams/.railroad
Ensure it fits the full pattern - there are many examples:
renameTable
::= 'RENAME' 'TABLE' oldName 'TO' newName
Be sure to maintain proper indentation!
Next, run the scripts/railroad.py [name] script to generate the SVG image.
For example:
python3 scripts/railroad.py renameTableDuring its final output, a markdown image with the appropriate syntax is printed:
Copy the image syntax below and paste it into your markdown file:
Copy this syntax and paste it into the markdown file where you want the diagram to appear.
The script requires:
- Java (to run the
rr.warfile) - Python (to execute the
railroad.pyscript)
Use LaTeX-style math between $ for inline or $$ for block equations:
$$
text
Inline equation: $f(x) = x^2$
Block equation:
$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$
Create diagrams using Mermaid syntax in code blocks:
graph TD
A[Start] --> B{Is it?}
B -- Yes --> C[OK]
C --> D[Rethink]
D --> B
B -- No --> E[End]
Syntax highlighting for many languages, including QuestDB SQL:
questdb-sql
SELECT
FROM trades
WHERE timestamp > dateadd('d', -1, now())
SAMPLE BY 1h;
Use special callouts for important information:
:::note
This is a note
:::
:::tip
This is a tip
:::
:::info
This is info
:::
:::warning
This is a warning
:::
:::danger
This is a danger warning
:::
Special React components available:
<RemoteRepoExample />: Include code examples from other QuestDB repos<TabItem />: Create tabbed content sections<Tabs />: Container for tab items
See examples in the documentation source files.
The coding style rules are defined by Prettier and enforced by Eslint
On top of this, we follow the rules set by the JavaScript Standard Style.
You do not need to run the linting task manually, Webpack will take care of that for you.