Quick Start

Get your first Asphinx documentation site up and running in minutes.

Create Your First Site

Step 1: Create Project Directory

mkdir my-docs
cd my-docs

Step 2: Initialize Project Structure

Create the basic directory structure:

mkdir -p content/{getting-started,user-guide}
mkdir -p theme
touch asphinx.toml

Your project structure should look like:

my-docs/
├── content/
│   ├── index.adoc
│   ├── getting-started/
│   └── user-guide/
├── theme/
└── asphinx.toml

Step 3: Create Main Index File

Create content/index.adoc:

= My Documentation Site
:toc: left
:sectanchors:
:sectlinks:

Welcome to my documentation site built with Asphinx!

== Getting Started

* xref:getting-started/installation.adoc[Installation Guide]
* xref:getting-started/basic-usage.adoc[Basic Usage]

== User Guide

* xref:user-guide/writing-content.adoc[Writing Content]
* xref:user-guide/configuration.adoc[Configuration]

== About

This site was generated using https://github.com/your-username/asphinx[Asphinx],
a modern AsciiDoc static site generator.

Step 4: Create Sample Content

Create content/getting-started/installation.adoc:

= Installation Guide

This guide will help you install the software.

== Prerequisites

Before you begin, ensure you have:

* A computer
* Internet connection
* Basic command line knowledge

== Installation Steps

. Download the software
. Extract the archive
. Run the installer
. Follow the setup wizard

== Verification

To verify the installation:

[source,bash]

software --version

You should see version information displayed.

Step 5: Configure Asphinx

Create asphinx.toml:

# Asphinx Configuration
no_default = false

[asciidoc]
extensions = ["asciidoctor-diagram"]

[asciidoc.attributes]
icons = "font"
toc = 1
experimental = ""
source-highlighter = "pygments"
sectanchors = ""
sectlinks = ""

Step 6: Set Up Theme

Clone or copy the default theme:

# If you have the Asphinx repository
cp -r /path/to/asphinx/theme/* theme/

# Or create a minimal theme structure
mkdir -p theme/{src,layouts}

Build the theme:

cd theme
npm install
npm run build
cd ..

Step 7: Generate Your Site

Run Asphinx to generate your documentation site:

asphinx --theme theme

This will:

Parse your AsciiDoc files
Generate HTML pages
Apply the theme
Create a searchable index
Output everything to the public/ directory

Step 8: Preview Your Site

Open the generated site in your browser:

# On macOS
open public/index.html

# On Linux
xdg-open public/index.html

# On Windows
start public/index.html

# Or use a local server
cd public
python -m http.server 8000
# Then visit http://localhost:8000

Understanding the Output

After running Asphinx, you’ll find:

public/
├── index.html              # Main page
├── getting-started/
│   └── installation.html   # Generated from .adoc files
├── assets/                 # Theme assets (CSS, JS, images)
├── cache.json             # Search index
└── ...                    # Other generated files

Next Steps

Congratulations! You’ve created your first Asphinx site. Here’s what to explore next:

Learn More About Content

Writing Content - Learn AsciiDoc syntax
Organizing Content - Structure your documentation
Cross References - Link between pages

Customize Your Site

Configuration - Customize Asphinx behavior
Theme Development - Create custom themes
Managing Assets - Add images and files

Advanced Features

Diagrams - Add PlantUML, Mermaid diagrams
Mathematical Expressions - Include LaTeX math
Search Configuration - Customize search behavior

Common Next Actions

Add More Content

Create additional pages by adding .adoc files to your content directory:

# Create a new section
mkdir content/tutorials
touch content/tutorials/index.adoc
touch content/tutorials/first-tutorial.adoc

Remember to link to new pages from your main index or section indexes.

Customize Styling

Modify the theme to match your brand:

cd theme
# Edit src/style.css for custom styles
# Modify src/main.tsx for React components
npm run build
cd ..
asphinx --theme theme

Set Up Automatic Building

Create a build script for easier regeneration:

#!/bin/bash
# build.sh
cd theme
npm run build
cd ..
asphinx --theme theme --minify
echo "Site built successfully!"

Make it executable:

chmod +x build.sh
./build.sh

Troubleshooting

Theme Build Fails

If the theme build fails:

cd theme
rm -rf node_modules package-lock.json
npm install
npm run build

Missing Dependencies

If you get errors about missing AsciiDoctor extensions:

gem install asciidoctor-diagram asciidoctor-mathematical

Permission Issues

If you get permission errors:

# Make sure you have write permissions
chmod -R u+w .

# Or run with appropriate permissions
sudo asphinx --theme theme

Getting Help

If you need help:

Check the Troubleshooting Guide
Review the FAQ
Visit our GitHub repository

Ready to dive deeper? Continue with the Basic Usage guide.