Basic Usage

Learn the fundamental concepts and workflows of Asphinx.

Command Line Interface

Asphinx provides a simple command-line interface for generating documentation sites.

Basic Command

asphinx --theme <theme-path>

Command Options

Option Description Default

Option	Description	Default
`--theme <PATH>`	Path to the theme directory	Required
`--minify`	Enable HTML minification for smaller file sizes	Disabled
`--help`	Show help information	-
`--version`	Show version information	-

--theme <PATH>

Path to the theme directory

Required

--minify

Enable HTML minification for smaller file sizes

Disabled

--help

Show help information

--version

Show version information

Examples

# Basic generation
asphinx --theme theme

# With minification (recommended for production)
asphinx --theme theme --minify

# Using a custom theme
asphinx --theme /path/to/custom-theme

# Show help
asphinx --help

Project Structure

Understanding the project structure is key to using Asphinx effectively.

Standard Layout

my-project/
├── content/                 # Your AsciiDoc content
│   ├── index.adoc          # Main entry point
│   ├── section1/
│   │   ├── index.adoc      # Section index
│   │   ├── page1.adoc      # Content pages
│   │   └── page2.adoc
│   └── section2/
│       └── ...
├── theme/                   # Theme files
│   ├── src/                # Theme source code
│   ├── layouts/            # HTML templates
│   └── assets/             # Static assets
├── asphinx.toml            # Configuration file
└── public/                 # Generated output (created by Asphinx)
    ├── index.html
    ├── section1/
    └── assets/

Content Organization

Index Files

Every directory should have an index.adoc file that serves as the entry point:

= Section Title

Brief description of this section.

== Pages in This Section

* xref:page1.adoc[Page 1 Title]
* xref:page2.adoc[Page 2 Title]
* xref:subsection/index.adoc[Subsection]

Cross-References

Use xref: to link between pages:

# Link to a page in the same directory
xref:other-page.adoc[Link Text]

# Link to a page in a subdirectory
xref:subdirectory/page.adoc[Link Text]

# Link to a page in a parent directory
xref:../parent-page.adoc[Link Text]

# Link to a specific section
xref:page.adoc#section-id[Section Title]

Content Creation Workflow

1. Plan Your Structure

Before writing content, plan your documentation structure:

Documentation Plan:
├── Getting Started
│   ├── Installation
│   ├── Quick Start
│   └── Basic Concepts
├── User Guide
│   ├── Writing Content
│   ├── Configuration
│   └── Advanced Features
└── Reference
    ├── API Documentation
    └── Configuration Options

2. Create Directory Structure

mkdir -p content/{getting-started,user-guide,reference}
touch content/index.adoc
touch content/getting-started/index.adoc
touch content/user-guide/index.adoc
touch content/reference/index.adoc

3. Write Content

Start with your main index file, then work on individual sections:

= My Documentation
:toc: left

Welcome to my documentation.

== Quick Navigation

* xref:getting-started/index.adoc[Getting Started]
* xref:user-guide/index.adoc[User Guide]
* xref:reference/index.adoc[Reference]

4. Build and Preview

# Build the theme (if modified)
cd theme && npm run build && cd ..

# Generate the site
asphinx --theme theme

# Preview locally
cd public && python -m http.server 8000

5. Iterate

Repeat the write-build-preview cycle until satisfied.

Working with AsciiDoc

Basic Syntax

Headings

= Document Title (Level 0)
== Chapter Title (Level 1)
=== Section Title (Level 2)
==== Subsection Title (Level 3)
===== Subsubsection Title (Level 4)

Text Formatting

*bold text*
_italic text_
`monospace text`
^superscript^
~subscript~

Lists

# Unordered list
* Item 1
* Item 2
** Nested item
** Another nested item

# Ordered list
. First item
. Second item
.. Nested numbered item
.. Another nested numbered item

# Definition list
Term 1:: Definition 1
Term 2:: Definition 2

Code Blocks

[source,javascript]

function hello() { console.log("Hello, World!"); }

Tables

[cols="1,2,1"]
|===
|Column 1 |Column 2 |Column 3

|Cell 1
|Cell 2
|Cell 3

|Cell 4
|Cell 5
|Cell 6
|===

Admonitions

NOTE: This is a note.

TIP: This is a tip.

IMPORTANT: This is important information.

CAUTION: This is a caution.

WARNING: This is a warning.

Build Process

Understanding how Asphinx processes your content helps optimize your workflow.

Processing Steps

Parse Index: Asphinx starts with content/index.adoc and follows xref: links
Generate HTML: Each .adoc file is converted to HTML using AsciiDoctor
Apply Theme: HTML is wrapped with the theme template
Create Search Index: Full-text search index is generated
Copy Assets: Theme assets are copied to the output directory
Minify (optional): HTML is minified if --minify flag is used

Performance Tips

Optimize Images

# Optimize images before adding to content
convert large-image.png -resize 800x600 optimized-image.png

Use Caching

Asphinx automatically caches processed content. To force a rebuild:

# Clear cache and rebuild
rm -rf .asphinx-cache
asphinx --theme theme

Parallel Processing

Asphinx processes files in parallel automatically. For large sites, ensure you have adequate system resources.

Development Workflow

Recommended Setup

Use Version Control

git init
git add .
git commit -m "Initial documentation setup"

Create Build Script

#!/bin/bash
# build.sh
set -e

echo "Building theme..."
cd theme
npm run build
cd ..

echo "Generating documentation..."
asphinx --theme theme --minify

echo "Documentation built successfully!"
echo "Open public/index.html to view the site."

Set Up Watch Mode (for development)

#!/bin/bash
# watch.sh
while inotifywait -r -e modify content/ theme/src/; do
    ./build.sh
done

Testing Your Documentation

Check Links

Verify all cross-references work:

# Generate site
asphinx --theme theme

# Check for broken links (using a link checker tool)
linkchecker public/index.html

Validate HTML

# Install HTML validator
npm install -g html-validate

# Validate generated HTML
html-validate public/**/*.html

Test Search

Generate the site with search index
Open in browser
Test search functionality with various queries

Troubleshooting Common Issues

Build Failures

AsciiDoctor Errors

Error: asciidoctor: FAILED: missing converter for backend 'html5'

Solution: Install required AsciiDoctor gems:

gem install asciidoctor asciidoctor-diagram

Theme Build Errors

Error: Cannot resolve module 'react'

Solution: Install theme dependencies:

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

Content Issues

Broken Cross-References

Warning: invalid cross reference: nonexistent-page.adoc

Solution: Check file paths and ensure referenced files exist.

Missing Images

Warning: image not found: images/missing.png

Solution: Verify image paths relative to the .adoc file.

Performance Issues

Slow Builds

For large documentation sites:

Use --minify only for production builds
Optimize images before adding them
Consider splitting large files into smaller sections

Large Output Size

Enable minification: --minify
Optimize images
Remove unused theme assets

Next Steps

Now that you understand the basics:

Learn about Project Structure in detail
Explore the User Guide for advanced features
Check out Configuration options
Try Theme Development

Getting Help

If you need assistance:

Review the Troubleshooting Guide
Check the FAQ
Visit our GitHub repository