OLake Website – Contributor Handbook
(The site is built with Docusaurus)
1. Prerequisites & Local Setup
Stack: Docusaurus 3.10, React 19, Tailwind CSS 4, strict MDX 3.
-
Node. Use the version in .nvmrc (currently 24; package.json requires 22 or newer).
nvm use
-
Clone and install
git clone https://github.com/datazip-inc/olake-docs.git
cd olake-docs
npm install
-
Clear the cache after every git pull, after npm install, and after editing any plugin file in src/plugins (the compile cache does not notice plugin changes). A "Module not found" or ReactContextError on every page usually means a stale cache.
npm run clear
-
Start the development server
npm start
Your default browser opens the local site. Some effects are production-only (for example the generated image sizes), so check final results in a build.
-
Build (this is what CI runs; broken links and anchors only produce warnings in the build output)
CI=true npm run build
npm run build runs docusaurus build and then the image sitemap script. It does not touch the repo: the Open Graph images in static/img/og/ are generated by hand with npm run og-images and committed (see 1.2). To preview the output: npm run serve.
-
Optional checks (not run in CI)
| Command | What it checks |
|---|
npm run typecheck | tsc --noEmit over the TypeScript sources |
npm run lint:content | MDX and front matter rules for docs, blog, customer-stories, learn and compare files; details in 1.2. Errors fail the command only when you run it yourself. |
npm run og-images -- --check | Fails if a blog cover has no 1200x630 social card in static/img/og/, or the cover changed since the card was rendered. Writes nothing. Run it after adding a post or changing a cover. |
1.1 Design system pointers
- Tokens:
src/css/tokens.css holds the --olake-* colors, type scale and spacing for light and dark. Use the Tailwind olake-* utilities (defined in src/css/custom.css) or var(--olake-*); do not hard-code hex values in components.
- UI primitives:
src/components/landing/ui/ (Button, Section, SectionHeading, Card, CtaBanner, LakesidePage). Build marketing pages from these.
- Page titles (h1): defined once in
src/css/typography.css; do not set h1 size or weight in a component.
- Swizzling: wrap the original (
@theme-original/<Component>) instead of copying it, so the swizzle survives Docusaurus upgrades.
1.2 Content checks (run locally, not enforced in CI)
CI (test-deploy.yml on pull requests, deploy.yml on master) only builds the site; none of the checks below block a merge, and the legacy MDX syntax (<!-- --> comments, {#id} heading ids, :::note Title) still compiles. They are there so you can catch problems before opening a PR.
Run it locally
npm run lint:content # errors fail (exit 1), warnings are listed
npm run lint:content -- blog/2026-10-01-my-post.mdx # limit to a file or folder
npm run lint:content -- --strict # warnings fail too (optional, not used in CI)
npm run build # broken links and anchors are printed as warnings
Errors (fail lint:content when you run it). The preferred form for each:
| Rule | Correct form |
|---|
html-comment | {/* comment */}, never <!-- comment --> (only <!-- truncate --> is allowed) |
heading-id | ## Install {/* #install */}, never ## Install {#install} |
admonition-title | :::tip[Before you start], never :::tip Before you start |
second-h1 (posts) | The title comes from front matter; start body headings at ## and do not use # ... or <h1> |
old-blog-url | [Post](/blog/my-post-slug/), never /blog/2024/05/01/... |
title-length (posts) | title: at most 70 characters (put longer SEO wording in seo_title:) |
title-missing, title-entity (posts) | title: "Postgres to Iceberg", with no & or & |
description-missing | Every post and doc has a description: |
authors-missing, author-unknown | authors: [anshika], where the id exists in the folder's authors.yml |
tags-missing, tags-count, tag-undefined | tags: [olake, iceberg]: at least one, at most 8, each defined in the folder's tags.yml |
image-missing, image-path, image-not-found | image: /img/blog/cover/my-cover.webp starts with / and the file exists under static/ |
slug-space, slug-duplicate | Slugs are unique per folder and contain no spaces |
filename-space | No spaces in file names |
frontmatter-yaml | Front matter parses as YAML (quote values that contain :) |
Warnings (listed only; fix them in files you touch). A summary written as :::tip[TL;DR] or ## TL;DR instead of the component, a description outside 120-160 characters, <br> outside a table, bold lines used as headings, code fences without a language, heading level jumps, absolute https://olake.io/... links, a post that does not end with <BlogCTA/>, docs/shared partials that have front matter, and a file name date that differs from the date: field.
TLDR component. Write the post summary once, right after the opening paragraph, as a component with a blank line after the opening tag and before the closing tag:
<TLDR>
- Point one
- Point two
</TLDR>
Internal links. Link to /docs/, not /docs/intro/. lint:content does not check this. The build prints a warning for a link to a route that does not exist, so read the build output. A plain <section id="x"> is not collected as an anchor, so a <Link to="#x"> to it is reported as broken even though the id exists; use <a href="#x"> for in-page links on custom pages.
Common fixes
This is the beginning of the README. Read the rest at the original. Read the full README ↗
