Skip to main content

Maintaining the Wiki

The Synctech documentation site is built with Docusaurus v3 and lives in apps/docs/ inside the monorepo. All content is plain Markdown — no CMS login required. Edit files, commit, and deploy.

Repository structure​

apps/docs/
├── blog/                   ← Changelog / release notes (one .md file per release)
│   └── authors.yml         ← Author definitions for blog posts
├── docs/                   ← All wiki articles
│   ├── intro.md            ← Homepage (slug: /intro)
│   ├── faq.md
│   ├── troubleshooting.md
│   ├── user-guides/        ← End-user module guides
│   └── admin-guides/       ← This section (admin-only references)
├── src/
│   ├── components/         ← Custom React components for the site
│   └── pages/index.tsx     ← Public homepage
├── static/                 ← Images and other static assets
├── docusaurus.config.ts    ← Site configuration (title, URL, navbar, footer)
└── sidebars.ts             ← Sidebar structure (auto-generated from folder structure)

Adding a new article​

  1. Create a .md file in the correct folder under docs/
  2. Add frontmatter at the top:
---
sidebar_position: 3        # Controls order within the section
---

# Article Title

Content here...
  1. The sidebar updates automatically — no changes to sidebars.ts needed

Adding a changelog entry​

Create a new file in blog/ named YYYY-MM-DD-slug.md:

---
slug: v1-2-0
title: "Release 1.2.0"
authors: [admin]
tags: [release]
---

Summary of the release shown on the blog index.

<!-- truncate -->

Full release notes below the truncate marker...

The authors: [admin] key maps to blog/authors.yml. Add new authors there if needed.

Open apps/docs/docusaurus.config.ts and update:

  • themeConfig.navbar.items — top navigation links
  • themeConfig.footer.links — footer columns and links

Adding images​

Place images in apps/docs/static/img/ and reference them in Markdown:

![Alt text](/img/my-screenshot.png)

Local preview​

cd apps/docs
npm start

This opens a live-reloading preview at http://localhost:3001 (or next available port).

Building and deploying​

Build only​

# From the repo root
npm run build:docs

Output goes to apps/docs/build/.

Deploy to docs.synctech.app​

# From the repo root — requires Firebase CLI logged in
npm run deploy:docs

This runs docusaurus build then firebase deploy --only hosting:docs.

First-time Firebase setup​

Before deploying for the first time:

  1. Create the second Hosting site in Firebase Console → your project → Hosting → Add another site → synctech-docs
  2. Add custom domain docs.synctech.app → verify DNS ownership
  3. Point a DNS A record to Firebase's provided IPs

The .firebaserc at the repo root already maps the docs target to the synctech-docs site ID.

Markdown features​

Docusaurus supports MDX (Markdown + JSX) and Docusaurus admonitions:

:::note
An informational callout
:::

:::tip
A helpful tip
:::

:::warning
Something to be careful about
:::

:::danger
A critical warning
:::

Tables, code blocks with syntax highlighting, and internal links ([link text](/docs/path)) all work out of the box.