Atlas Document Management System

A Rust-based document collection management system with CLI, library, and web interfaces for processing markdown-based documentation with support for cross-collection references, link validation, and export to self-contained directories.

Project Structure

This is a Rust workspace containing multiple packages:

• lib - Core library for document collection management
• atlas - Command-line interface
• web - Web server for interactive wiki-style documentation
• examples - Example applications demonstrating library usage

Quick Start

# Build all packages
./build.sh

# Build individual packages
cd lib && cargo build
cd atlas && cargo build
cd web && cargo build

# Run the CLI
cd atlas && cargo run -- --help

# Run examples
cd examples && cargo run --bin basic_usage

Features

• Collection scanning: Automatically discover collections marked with .collection files
• Cross-collection references: Link between pages in different collections using collection:page syntax
• Include directives: Embed content from other pages with !!include collection:page
• Link validation: Detect broken links to pages, images, and files
• Export: Generate self-contained directories with all dependencies
• Access control: Group-based ACL via .group files
• Git integration: Automatically detect repository URLs

Installation

Build from source

./build.sh

The binary will be at target/release/atlas.

Install to PATH

./install.sh

Installs to ~/.local/bin/atlas.

CLI Usage

Scan collections

atlas scan --path /path/to/docs
atlas scan --path /path/to/docs --ignore node_modules --ignore .git

Export collections

# Export to default location (/tmp/atlas)
atlas export --path /path/to/docs

# Export with reset (clear destination first)
atlas export --path /path/to/docs --reset

# Export to custom location
atlas export --path /path/to/docs --destination /path/to/export

# Process include directives during export
atlas export --path /path/to/docs --include

List collections and pages

atlas list --path /path/to/docs

Show validation errors

atlas errors --path /path/to/docs

Get page content

atlas page --key collection_name:page_name --path /path/to/docs

Read from exported doctree

# List collections
atlas read collections

# List pages in a collection
atlas read pages --collection mycolection

# Get page content
atlas read page --collection mycollection --page mypage

# List images
atlas read images --collection mycollection

# List files
atlas read files --collection mycollection

Directory Structure

Source Structure

docs/
├── collection1/
│   ├── .collection           # Marks as collection (optional: name:custom_name)
│   ├── read.acl              # Optional: group names for read access
│   ├── write.acl             # Optional: group names for write access
│   ├── page1.md
│   ├── subdir/
│   │   └── page2.md
│   └── img/
│       └── logo.png
├── collection2/
│   ├── .collection
│   └── intro.md
└── groups/                   # Special collection for ACL groups
    ├── .collection
    ├── admins.group
    └── editors.group

Export Structure

/tmp/atlas/
├── content/
│   └── collection_name/
│       ├── page1.md          # Pages at root of collection dir
│       ├── page2.md
│       ├── img/              # All images in img/ subdirectory
│       │   └── logo.png
│       └── files/            # All other files in files/ subdirectory
│           └── document.pdf
└── meta/
    └── collection_name.json  # Collection metadata

File Formats

.collection

name:custom_collection_name

If empty or name not specified, uses directory name.

.group

// Comments start with //
user@example.com
*@company.com
include:other_group

ACL files (read.acl, write.acl)

admins
editors

One group name per line.

Link Syntax

Page links

[text](page_name)           # Same collection
[text](collection:page)     # Cross-collection

Image links

![alt](img/image.png)              # Same collection
![alt](collection:img/image.png)   # Cross-collection

Include directives

!!include page_name
!!include collection:page_name

Name Normalization

Page and collection names are normalized:

1. Convert to lowercase
2. Replace - with _
3. Replace / with _
4. Remove .md extension
5. Strip numeric prefix (e.g., 03_page → page)
6. Remove special characters

Supported Image Extensions

• .png, .jpg, .jpeg, .gif, .svg, .webp, .bmp, .tiff, .ico

Library Usage

use doctree::{DocTree, ExportArgs};

fn main() -> doctree::Result<()> {
    // Create and scan
    let mut doctree = DocTree::new("mydocs");
    doctree.scan(Path::new("/path/to/docs"), &[])?;
    doctree.init_post()?;  // Validate links

    // Access pages
    let page = doctree.page_get("collection:page")?;
    let content = page.content()?;

    // Export
    doctree.export(ExportArgs {
        destination: PathBuf::from("/tmp/atlas"),
        reset: true,
        include: false,
    })?;

    Ok(())
}

DocTreeClient (for reading exports)

use doctree::DocTreeClient;

fn main() -> doctree::Result<()> {
    let client = DocTreeClient::new(Path::new("/tmp/atlas"))?;

    // List collections
    let collections = client.list_collections()?;

    // Get page content
    let content = client.get_page_content("collection", "page")?;

    // Check existence
    if client.page_exists("collection", "page") {
        println!("Page exists!");
    }

    Ok(())
}

Project Structure

atlasserver_rust/
├── Cargo.toml           # Project configuration
├── build.sh             # Build script
├── install.sh           # Install script
├── README.md            # This file
└── src/
    ├── lib.rs           # Library entry point
    ├── main.rs          # CLI application
    ├── doctree.rs       # DocTree container
    ├── collection.rs    # Collection implementation
    ├── page.rs          # Page implementation
    ├── link.rs          # Link parsing
    ├── group.rs         # ACL groups
    ├── client.rs        # DocTreeClient
    ├── types.rs         # Core types
    ├── utils.rs         # Utilities
    └── error.rs         # Error types