AtlasClient

A simple API for accessing document collections exported by the atlas module.

What It Does

AtlasClient provides methods to:

• List collections, pages, files, and images
• Check if resources exist
• Get file paths and content
• Access metadata (links, errors)
• Copy images from pages

Quick Start

import incubaid.herolib.web.atlas_client

// Create client
mut client := atlas_client.new(export_dir:'${os.home_dir()}/hero/var/atlas_export')!

// List collections
collections := client.list_collections()!

// Get page content
content := client.get_page_content('my_collection', 'page_name')!

// Check for errors
if client.has_errors('my_collection')! {
    errors := client.get_collection_errors('my_collection')!
}

Export Structure

Atlas exports to this structure:

export_dir/

Key Methods

Collections:

• list_collections() - List all collections

Pages:

• list_pages(collection) - List pages in collection
• page_exists(collection, page) - Check if page exists
• get_page_content(collection, page) - Get page markdown content
• get_page_path(collection, page) - Get page file path

Files & Images:

• list_files(collection) - List non-page, non-image files
• list_images(collection) - List image files
• get_file_path(collection, file) - Get file path
• get_image_path(collection, image) - Get image path
• copy_images(collection, page, dest) - Copy page images to dest/img/
• copy_files(collection, page, dest) - Copy page files to dest/files/

Metadata:

• get_collection_metadata(collection) - Get full metadata
• get_page_links(collection, page) - Get links from page
• get_collection_errors(collection) - Get collection errors
• has_errors(collection) - Check if collection has errors

Naming Convention

Names are normalized using name_fix():

• My_Page-Name.md → my_page_name
• Removes: dashes, special chars
• Converts to lowercase
• Preserves underscores

Example

See examples/data/atlas_client/basic_usage.vsh for a complete working example.

See Also

• lib/data/atlas/ - Atlas module for exporting collections
• lib/web/doctreeclient/ - Alternative client for doctree collections

fn new(args AtlasClientArgs) !&AtlasClient

Create a new AtlasClient instance The export_dir should point to the directory containing content/ and meta/ subdirectories

enum LinkFileType {
	page  // Default: link to another page
	file  // Link to a non-image file
	image // Link to an image file
}

enum LinkStatus {
	init
	external
	found
	not_found
	anchor
	error
}

struct AtlasClient {
pub mut:
	redis      &redisclient.Redis
	export_dir string // Path to the atlas export directory (contains content/ and meta/)
}

AtlasClient provides access to Atlas-exported documentation collections It reads from both the exported directory structure and Redis metadata

fn (mut c AtlasClient) get_page_path(collection_name string, page_name string) !string

get_page_path returns the path for a page in a collection Pages are stored in {export_dir}/content/{collection}/{page}.md

fn (mut c AtlasClient) get_file_path(collection_name_ string, file_name_ string) !string

get_file_path returns the path for a file in a collection Files are stored in {export_dir}/content/{collection}/{filename}

fn (mut c AtlasClient) get_image_path(collection_name_ string, image_name_ string) !string

get_image_path returns the path for an image in a collection Images are stored in {export_dir}/content/{collection}/{imagename}

fn (mut c AtlasClient) page_exists(collection_name string, page_name string) bool

page_exists checks if a page exists in a collection

fn (mut c AtlasClient) file_exists(collection_name string, file_name string) bool

file_exists checks if a file exists in a collection

fn (mut c AtlasClient) image_exists(collection_name string, image_name string) bool

image_exists checks if an image exists in a collection

fn (mut c AtlasClient) get_page_content(collection_name string, page_name string) !string

get_page_content returns the content of a page in a collection

fn (mut c AtlasClient) list_collections() ![]string

list_collections returns a list of all collection names Collections are directories in {export_dir}/content/

fn (mut c AtlasClient) list_pages(collection_name string) ![]string

list_pages returns a list of all page names in a collection Uses metadata to get the authoritative list of pages that belong to this collection

fn (mut c AtlasClient) list_files(collection_name string) ![]string

list_files returns a list of all file names in a collection (excluding pages and images)

fn (mut c AtlasClient) list_images(collection_name string) ![]string

list_images returns a list of all image names in a collection

fn (mut c AtlasClient) list_pages_map() !map[string][]string

list_pages_map returns a map of collection names to a list of page names within that collection. The structure is map[collectionname][]pagename.

fn (mut c AtlasClient) list_markdown() !string

list_markdown returns the collections and their pages in markdown format.

fn (mut c AtlasClient) get_collection_metadata(collection_name string) !CollectionMetadata

get_collection_metadata reads and parses the metadata JSON file for a collection Metadata is stored in {export_dir}/meta/{collection}.json

fn (mut c AtlasClient) get_page_links(collection_name string, page_name string) ![]LinkMetadata

get_page_links returns the links found in a page by reading the metadata

fn (mut c AtlasClient) get_collection_errors(collection_name string) ![]ErrorMetadata

get_collection_errors returns the errors for a collection from metadata

fn (mut c AtlasClient) has_errors(collection_name string) bool

has_errors checks if a collection has any errors

fn (mut c AtlasClient) copy_images(collection_name string, page_name string, destination_path string) !

fn (mut c AtlasClient) copy_files(collection_name string, page_name string, destination_path string) !

copy_files copies all non-image files from a page to a destination directory Files are placed in {destination}/files/ subdirectory Only copies files referenced in the page (via links)

struct AtlasClientArgs {
pub:
	export_dir string @[required] // Path to atlas export directory
}

struct CollectionMetadata {
pub mut:
	name   string
	path   string
	pages  map[string]PageMetadata
	files  map[string]FileMetadata
	errors []ErrorMetadata
}

CollectionMetadata represents the metadata stored in meta/{collection}.json

struct ErrorMetadata {
pub mut:
	category string
	page_key string
	message  string
	line     int
}

struct FileMetadata {
pub mut:
	name string // name WITH extension (e.g., "image.png", "data.csv")
	path string // relative path in export (e.g., "img/image.png" or "files/data.csv")
}

struct LinkMetadata {
pub mut:
	src                    string
	text                   string
	target                 string
	line                   int
	target_collection_name string
	target_item_name       string
	status                 LinkStatus
	file_type              LinkFileType
}

struct PageMetadata {
pub mut:
	name            string
	path            string
	collection_name string
	links           []LinkMetadata
}