Docs
docs-contribute
How to Contribute

How to Contribute

This is the practical guide for contributing to docs.mediakind.com. For writing style, see the Style Guide. For page templates and structure, see Page Structure.

All documentation is written in markdown (opens in a new tab). Alongside regular markdown, the site includes some custom components for rendering elements such as callouts, cards, and workflows.

See the Component Reference and Markdown Reference for more information.

How Publishing Works

  • The documentation site is hosted in the https://dev.azure.com/mediakind/UX/_git/mk-online-doc (opens in a new tab) ADO repository.
  • main is production (docs.mediakind.com). All approved PRs merge here.
  • Contributors create a feature branch, make changes, and open a PR into main one changes are ready to be approved.
  • PRs always require approval before merging.
  • A Vercel preview URL is automatically posted to your PR so reviewers can check your changes in the browser before approving.

Rules

  • Never commit directly to main.
  • Always branch off the latest main.
  • Keep PRs focused — one topic or section per PR where possible.
  • If you changed a page URL, mention it in the PR description.

Quick Contributions via ADO UI (Non-Technical)

  1. Open the repo in Azure DevOps (mediakind / UX / Repos / Files / mk-online-doc).
  2. Make sure you are on the main branch.
  3. Navigate to the page you want to edit inside pages/.
  4. Click Edit and make your changes.
  5. When saving, choose Create a new branch and name it docs/<short-description>.
  6. Open a PR from your branch into main.
  7. Add a reviewer — any relevant team member plus the docs maintainer.
  8. A Vercel preview link will appear in the PR automatically. Include it in your review request so reviewers can check the rendered output.
  9. Once approved, merge.

Standard Workflow (Command Line)

Prerequisites

  • Node.js (version 20 or higher)
  1. Clone the repo:
git clone <repo-url>
cd <repo-folder>
  1. Install dependencies:
pnpm install
# npm install
  1. Make sure you are on a fresh copy of main:
git checkout main
git pull origin main
  1. Create your feature branch:
git checkout -b docs/<short-description>

  1. Make your changes:

    • Edit files inside pages/.
    • If you create or remove a page, update the relevant _meta.json so it appears correctly in the sidebar.

  2. Run local checks before pushing:

pnpm dev   # check it looks right in the browser
# npm run dev
pnpm build # check there are no build errors
#npm run build
  1. Commit your changes:
git add -A
git commit -m "docs: <short summary of change>"
  1. Push your branch:
git push -u origin docs/<short-description>

  1. Open a PR in ADO:

    • Source: docs/<short-description>
    • Target: main
    • Add reviewers: relevant team members + docs maintainer.

  2. A Vercel preview URL will be posted automatically as a PR comment within a minute or two. Share this with your reviewers.

  3. Once approved, merge. Your changes go live within 10 minutes.

Site Structure

ConceptDetail
Doc pagesAll pages live inside pages/
URL mappingFile path → URL path (e.g. pages/mkio/getting-started.mdx → /mkio/getting-started)
Folder landing pageName the file index.mdx
Sidebar order & labelsControlled by _meta.json in each folder

Common Mistakes

  • Don't push to main directly.
  • Don't forget to pull latest main before branching.
  • Don't change _meta.json unless you're adding or removing a page. Sidebar order changes affect everyone.
  • Don't include .mdx in internal links — use /mkio/getting-started not /mkio/getting-started.mdx.

Further Reading

Style Guide