(The site is built with Docusaurus)
-
Clone the repository
git clone https://github.com/datazip-inc/olake-docs.git
-
Install dependencies
npm i
-
Verify the build
npm run build
A successful build confirms there are no compile-time errors.
-
Start the development server
npm run start
Your default browser will automatically open the local site.
| Directory | When to use |
|---|---|
/blog |
General OLake topics |
/iceberg |
Iceberg-specific topics |
-
Navigate to the correct directory.
-
Create an MDX file:
YYYY-MM-DD-blog-slug.mdx. The date reflects the publish date, not the commit date. -
Copy the front-matter (metadata) from an existing post and update it.
-
Manage authors
- Each directory has its own
authors.yml. - Add new authors here before referencing them in a post.
- Each directory has its own
-
Append
<BlogCTA/>as the final line of every blog post.
- Root folder:
static/img/blog/ - Cover images:
static/img/blog/cover/<slug>-cover.png - Inline images:
static/img/blog/YYYY/MM/<slug>-N.png
Example – slug flatten-array, published May 2025:
static/img/blog/cover/flatten-array-cover.png
static/img/blog/2025/05/flatten-array-1.png
static/img/blog/2025/05/flatten-array-2.png
-
Create reusable React (
.tsx) components insrc/components.- Keep them text-agnostic and modular.
-
Before creating, scan existing components for reuse.
-
To expose a component globally in MDX, import it once in
src/theme/MDXComponents/Index.js.- Afterwards, you can use
<MyComponent/>in any file under/blog,/docs, or/iceberg. - HTML pages in
src/pagesstill require manual imports.
- Afterwards, you can use
- Create the MDX file under
/docs. - Register the file (and its order) in
sidebars.js. Order-of-appearance in the sidebar is defined here.
- Place reusable snippets in
docs/shared/. - Import them in
src/theme/MDXComponents/Index.js. - Use them anywhere with the usual
<SharedComponent/>syntax.
| Topic | Details |
|---|---|
| Redirects | Configure at the end of docusaurus.config.js. |
CNAME |
Do not delete static/CNAME; GitHub Pages needs it for olake.io. |
| Public files | Any asset in static is publicly accessible (e.g. /reddit.json). |
| Next.js | We may switch to the Next.js plug-in later for Lighthouse gains. |
| Embedding media | Images: Markdown ; use raw HTML for size control.Videos: embed via HTML. |
| MDX & HTML | MDX accepts all HTML except tables (use Markdown tables). |
| Docusaurus features | Components like <Tabs>, <TabItem>, :::info, etc. are native—see their docs. |
```py title="docker-compose.yml"
# code here
````
Supported lexers: py, bash, sh, js, jsx, go, yaml, yml, text, …
## Heading ✅
### Heading ✅
## **Heading** ❌
Use Docusaurus swizzle to override core components and UI of how . Swizzled files live in src/theme/.
We have already swizzled: blog pages, doc pages, navbar, and footer.
Add work-in-progress content to the /drafts folder; it will not be published.
git add . # stage all changes
git commit -m "Message" # commit
git commit -am "Message" # add + commit tracked files
git pull # fetch & merge
git push # push current branch
git branch # list branches
git status # show working tree status
git checkout -b <new-branch> # create and switch
git switch <branch> # switch existing branchgit push --set-upstream origin <branch-name># 1. Make sure local master is current
git switch master
git pull origin master
# 2. Create a feature branch
git checkout -b blog/your-slug # or docs/your-topic, etc.
# 3. Work on your changes
# (add blog MDX, images, authors.yml, sidebar entry, etc.)
# 4. Stage & commit
git add .
git commit -m "Add <your-slug> blog to OLake docs"
# 5. Push and open a PR
git push --set-upstream origin blog/your-slug-
Finish work on the first branch and push.
-
Ensure
masteris up to date:git switch master git pull origin master
-
Create your next branch:
git checkout -b blog/second-slug
-
Repeat the add → commit → push cycle.
Tips • Git can feel tricky—refer to official docs, blog posts, or ask in Slack. • Always branch from
masterunless directed otherwise.
- Check the official Docusaurus docs.
- For Git issues, consult documentation or ChatGPT.
Happy writing and shipping content!