Quick Start

Get your technical documentation site up and running in under five minutes. This guide walks you through installation, creating your first article, and previewing your work locally.

Prerequisites

You'll need Node.js 18+ and a package manager (npm, pnpm, or yarn) installed on your machine.

Overview

This documentation template is built with Astro and MDX - the same stack used by Cloudflare's developer docs. It gives you:

  • Native Markdown and MDX support with zero-config setup
  • Dark/light theme with system preference detection
  • Section-scoped navigation with breadcrumbs
  • Table of contents with scroll-spy highlighting
  • Syntax-highlighted code blocks with copy buttons
  • Callout components for notes, warnings, and tips

Installation

Prerequisites

Make sure you have the latest LTS version of Node.js installed. You can verify with:

terminal
node --version
# v20.11.0 or later

  1. Clone the template

    Grab the starter template from the repository:

    terminal
    git clone https://github.com/your-org/tech-docs.git
cd tech-docs

  2. Install dependencies

    terminal
    npm install

  3. Start the dev server

    terminal
    npm run dev

    Your site will be available at http://localhost:4321 with hot-reload enabled.

Your First Article

Frontmatter

Every article starts with YAML frontmatter that defines its metadata. Create a new file at src/pages/guides/my-article.mdx:

src/pages/guides/my-article.mdx
---
title: My First Article
description: A quick introduction to writing technical docs
pubDate: 2026-09-01
tags: [getting-started, mdx]
---

# My First Article

Welcome to the docs! This is your first article written in MDX.

Writing Content

MDX lets you mix Markdown with interactive components. Here's a callout:

Watch out

Always wrap code examples in fenced code blocks with a language tag for proper syntax highlighting.

And a code example with a filename header:

src/config.ts
import { defineConfig } from 'astro/config';

export default defineConfig({
  site: 'https://docs.example.com',
  markdown: {
    shikiConfig: {
      theme: 'github-dark',
    },
  },
});

Preview & Build

When you're ready to see the production build:

terminal
npm run build
npm run preview

The build outputs static files to dist/ that you can deploy anywhere - Vercel, Cloudflare Pages, Netlify, or a plain web server.

Done!

You now have a fully functional documentation site. Check out the Writing Articles guide for advanced formatting, or the Components reference for everything you can embed.

Next Steps

← Previous
Introduction