Getting Started With Garnet Wiki

Comprehensive reference for getting started with garnet wiki covering essential concepts, practical examples, and production best practices.

You are a software engineer joining a team that uses Garnet Wiki — a collaborative, versioned documentation platform built on top of standard web technologies. This guide is for you: you have just landed on the wiki’s homepage, and you need to become productive within the next hour. Whether you’re onboarding, contributing to a project, or debugging a documentation issue, this guide walks you through the essential workflows, common pitfalls, and the subtle details that turn a casual contributor into a reliable wiki member.

The Garnet Wiki homepage is a single HTML page served from https://wiki.garnet.dev. It displays a list of pages in a sidebar, with the current page rendered in the main content area. Each page has a title, a body, and metadata such as author, last edited, and revision history. The sidebar is collapsible and searchable; clicking a page title loads it into the main area.

To move between pages, use the sidebar or the breadcrumb trail at the top. The breadcrumb trail looks like:

Home > Projects > Garnet Core > Getting Started

Clicking any link in the trail navigates to that page. The current page is highlighted in the sidebar.

Creating a New Page

You want to write documentation for a new feature. Start by clicking the + New Page button in the sidebar, which opens a modal with:

When you create a page, Garnet Wiki generates a unique slug from the title. For example, “Getting Started with Garnet Wiki” becomes getting-started-with-garnet-wiki.

The page is saved as a JSON file in pages/ under the wiki’s content directory. The file structure is:

pages/
├── getting-started-with-garnet-wiki.json
├── projects/
│   └── garnet-core/
│       └── index.json
└── home.json

The JSON schema is:

{
  "title": "Getting Started with Garnet Wiki",
  "slug": "getting-started-with-garnet-wiki",
  "parent": "projects/garnet-core",
  "tags": ["onboarding", "documentation", "garnet"],
  "content": "# Getting Started with Garnet Wiki\n\nYou are a software engineer joining a team that uses Garnet Wiki...",
  "created_at": "2025-04-05T10:30:00Z",
  "updated_at": "2025-04-05T10:30:00Z",
  "author": "[email protected]",
  "version": 1
}

The content field is Markdown, and all rendering is done server-side using a standard Markdown parser (like CommonMark).

Common Pitfalls When Creating Pages

Editing a Page

To edit a page, click the Edit button in the top-right corner. The page opens in a full-screen editor with a split view:

The editor supports:

  def hello(name: str) -> str:
      return f"Hello, {name}!"

Real-Time Collaboration and Versioning

When you save, the editor sends a PUT request to:

PUT /api/pages/{slug}

with the following JSON body:

{
  "content": "# Getting Started with Garnet Wiki\n\nYou are a software engineer joining a team that uses Garnet Wiki...\n\n## Creating a New Page\n\nYou want to write documentation for a new feature...",
  "tags": ["onboarding", "documentation", "garnet"],
  "author": "[email protected]",
  "version": 2
}

The server responds with 200 OK and a JSON payload:

{
  "success": true,
  "page": {
    "slug": "getting-started-with-garnet-wiki",
    "updated_at": "2025-04-05T10:45:20Z",
    "version": 2
  }
}

Each save increments the version number. The version history is accessible via a History tab on the page. Clicking a version shows a diff between that version and the current one.

Versioning and Reverting

Clicking the History tab displays a list of all versions, with:

To revert to a previous version, click the version number and select Restore. The server sends:

POST /api/pages/{slug}/revert

with body:

{
  "to_version": 1,
  "reason": "Fix typo in first paragraph"
}

The server updates the content, updated_at, and version fields, and creates a new entry in the revision log.

Linking Pages

You want to link from the “Getting Started” page to a “Architecture Overview” page. Use the Insert Link button in the editor.

The syntax is:

[Architecture Overview](/architecture-overview)

This creates a hyperlink that points to the architecture-overview.json file.

If the target page does not exist, the link appears in red in the preview. When you save, the server validates all links and returns a 400 Bad Request if any link is broken:

{
  "errors": [
    {
      "type": "link_not_found",
      "path": "/architecture-overview",
      "message": "Page not found at path 'architecture-overview'"
    }
  ]
}

The editor highlights the invalid link in red and shows a tooltip with the error.

Linking to Specific Sections

To link to a section within a page, use the # syntax:

[See the Overview section](/architecture-overview#overview)

The server resolves the section by searching for an h2 or h3 heading with the text Overview. If no matching heading exists, the link is marked as section not found.

Adding and Managing Media

You upload an image using the image icon. The editor:

  1. Opens a file dialog.
  2. Uploads the file to POST /api/media with multipart/form-data.
  3. Returns a JSON response with the media ID:
{
  "id": "abc123",
  "url": "/media/abc123.png",
  "filename": "diagram.png",
  "size": 123456,
  "created_at": "2025-04-05T11:00:00Z"
}

The editor inserts the image with:

![Architecture Diagram](/media/abc123.png)

You can update the image by clicking its thumbnail and selecting a new file, or by dragging a new image into the editor.

Managing Page Permissions

Pages can have different access levels: public, team, and private.

The permissions field in the page JSON is an array of objects:

{
  "permissions": [
    {
      "type": "team",
      "name": "garnet-core-team"
    },
    {
      "type": "user",
      "email": "[email protected]"
    }
  ]
}

When a user visits a page, the server checks their identity via a standard Authorization header:

Authorization: Bearer <jwt-token>

The JWT token is issued by the wiki’s auth service and contains:

{
  "sub": "[email protected]",
  "roles": ["developer", "wiki-editor"],
  "teams": ["garnet-core-team", "docs-team"]
}

The server checks:

  1. Is the user in the teams list?
  2. Do they have the required roles?
  3. Is the page’s permissions list satisfied?

If not, the server returns 403 Forbidden with a message:

{
  "error": "Permission denied",
  "details": [
    "User not a member of 'garnet-core-team'",
    "Missing required role: 'wiki-editor'"
  ]
}

Each page has a Share button. Clicking it generates a link with a query parameter ?version=2 to lock the page to a specific version.

To embed a page in another site, use the Embed button. It returns an <iframe> snippet:

<iframe
  src="https://wiki.garnet.dev/getting-started-with-garnet-wiki?embed=true"
  width="800"
  height="600"
  frameborder="0"
  allowfullscreen
></iframe>

The embed=true query parameter enables a minimal UI: only the page title and navigation, no sidebar or header.

Troubleshooting Common Errors

  {
    "error": "Page not found",
    "requested_slug": "getting-started-with-garnet-wiki",
    "available_slugs": [
      "getting-started",
      "home",
      "projects/garnet-core"
    ]
  }

This helps you spot typos in slugs or missing parent pages.

  {
    "error": "Version conflict",
    "current_version": 3,
    "expected_version": 2,
    "content": "..."
  }

The editor shows a modal: “Someone else updated this page. Your version is out of date. Do you want to merge or overwrite?”

  curl -X POST \
       -H "Authorization: Bearer $JWT" \
       -F "[email protected]" \
       -F "title=Architecture Diagram" \
       https://wiki.garnet.dev/api/media

If the server returns 415 Unsupported Media Type, the Content-Type header is incorrect.

Final Checklist: Your First Wiki Session

  1. Create a new page titled “My First Contribution” under Contributing To Garnet Wiki.
  2. Add a code block with a curl command to fetch a page.
  3. Link to the “Architecture Overview” page.
  4. Upload an image from your local machine.
  5. Edit the page and save with a version note.
  6. Check the page history and revert to a previous version.
  7. Share the page with a versioned link.
  8. Verify that the page is accessible via the sidebar and breadcrumbs.

When you finish, you’ve not only contributed to the wiki — you’ve internalized its workflows, failure modes, and conventions. You are now a reliable member of the Garnet Wiki community.

This page was rewritten on 18 October 2026. It replaced a templated version that was not specific to its own title. How these pages are written and checked. If anything here is wrong, tell us at [email protected] and we will correct it.