Changelog

%%{init: {'theme':'neutral'}}%%
timeline
    section Alpha Phase
        alpha-0.5
            : 📅 Aug 03, 2025
			: Scrollable tables
			: Add mermaid support
        alpha-0.6
            : 📅 Aug 05, 2025
			: Add fall animation on selected section
			: Support url routing per section
        alpha-1.0
            : 📅 Aug 14, 2025
			: Add ref import support

2025-08-14 (alpha-1.0)

• Add ref support, to divide and modularize documentation in separate files

2025-08-05 (alpha-0.6)

• Add fall animation on selected section
• Support section url routing (now shareable links per section)

2025-08-03 (alpha-0.5)

• Add table wrapper to scroll on smaller viewports
• Listen to ESC key to close nav drawer (on smaller viewports)
• Add animation for selected content transition
• Add mermaid support inside md summary context
• Refactor JS usage, move to use jsdeliver

2025-08-02 (alpha-0.4)

• Improve markdown context detector due conflicts within code blocks
• Create installer script (curl based)

2025-07-30 (alpha-0.3)

• Expose Content type section, supporting mardown
• Update official documentation with available features

2025-07-24 (alpha-0.2)

• Reinforcement of rawBlocks generation
• First version of official documentation deployed

2025-07-23 (alpha-0.1)

• Initial publication of Amauta documentation

Amauta focuses on fulfilling the need to create maintainable, readable and intuitive documentation. It defines a new protocol to declare documentation for RESTful APIs, marked-up content, SDKs and virtually anything that could be used in collaborative teams, open source tools or personal projects.

Installation

1. Using install script (Linux)

Just run:

wget -qO - https://raw.githubusercontent.com/luislve17/amauta/release/install.sh | bash

You will get prompted to move the download binary to /usr/local/bin.

2. Using install script (Linux + other systems)

You may also find the precompiled binary in the releases page of the project.

Once downloaded, it is recommended to put it in a binary folder that your $PATH environment variable is aware of. You should finally be able to do:

$ amauta -v
Amauta: version alpha-1.0

CLI Usage

Amauta generates documentation from a manifest file. Skipping the trivial (but valid for the linter & renderer) example of an empty file, a minimal documentation would look something like this:

# ./dist/manifest.amauta
[[@groups]]
intro: Introduction

[[Hello doc@content]]
group: intro
summary: Hello from Amauta!

Which defines:

1. A group named intro
2. A content-type section, linked to the intro group, and with its corresponding summary

Executing the command:

amauta --render -i ./dist/manifest.amauta

Amauta will generate the given doc as an .html file in the default relative path ./dist/doc.html.

More available options will be explored later when reviewing the CLI, but in general terms and depending on the version, one would have the following from the CLI interface:

$ amauta --h                               
Usage of Amauta CLI (alpha-1.0):
-h	Show this help
-v	Build version
-i	Input path
-o	Output HTML file path (defaults to './dist/doc.html')
-lint	Lint doc manifest
-render	Render HTML from doc manifest
-theme	Name of the selected theme (available: 'default', 'dark')

Amauta focuses on achieving a simple syntax, with intuitive rules that work in separate contexts.

Section

Sections are the core documentation entity. They define a finite text region that renders in a particular way depending on its type. e.g.: Root, Tags, Groups, Content.

Base syntax

For Amauta, the syntax must be simple and reliable. In 99% of use cases:

Base rules

There only exists one rule (more of a suggestion) and it comes from experience on how to avoid doing things wrong:

We highly encourage avoiding indentation while writing documentation

We will see later how to approach use cases like nested object declarations.

The real challenge is adapting this to different contexts—creating a section is not the same as defining a 200-response schema. Nevertheless, the same rules apply unless the context justifies a more detailed declaration of intent.

Headers

Define the beginning of a section. All content below it, until a new header (or EOF) will be treated as content declared by the header.

For example:

[[@groups]]

Indicates the key-type of an item (@) as groups. This is a reserved section, since it's identified by the type itself and is required by the linter/renderer to perform operations.

[[Products@api#public,sales]]

Declares:

• A particular name "Products" for this section
• Of type (@) api
• And tagged (#) as public and sales

This is not a reserved section since the user is allowed to declare it as needed, and not creating it won't block the linter/renderer from performing its operations.

Fields

Define details on specific attributes, depending on the context where these are declared.

For example:

[[Products@api#public,sales]]
id@str: Product's id
name@str: Product's name
calories?float#private: Product's caloric content

Declares a product's:

• id, which is a string (typed by @)
• name, which also types as string
• And calories, typed as an optional (?) float (real number) and tagged (#) as private

All of these have their corresponding description, declared after the : character.

An equivalent declaration of these 4 lines of doc, but for other protocols would look something like:

Products:
  type: object
  properties:
    id:
      type: string
      description: Product's id
    name:
      type: string
      description: Product's name
    calories:
      type: number
      format: float
      description: Product's caloric content
  required:
    - id
    - name

Which when scaling to a more complex manifest as a product grows, exemplifies the rule made at the beginning.

Root

[[@root]]
LogoUrl: <url>

Specifies global setup or resources. (under development)

Example

[[@root]]
LogoUrl: https://raw.githubusercontent.com/luislve17/amauta/refs/heads/main/assets/amauta-banner.svg

Tags

[[@tags]]
<id>#<color>:<description>

Specifies available tags to use. As of the current build version, there is no particular use yet (under development).

Example

[[@tags]]
public#00FF00: Public API
internal#AAAAAA: Internal use only
deprecated#FF6F61: Will be removed soon
under-dev#FFD966: Still under development
beta#87CEEB: Beta feature
admin#FF1493: Admin only

Groups

[[@groups]]
<id>: <description>

Specifies group definitions for organizing sections.

Example

[[@groups]]
dev: Development
getting-started: Getting started
key-section: Key sections

Content

[[<name>@content#<tag_ids>]]
group: <group-id>
summary: <summary>

Declares an all-purpose doc section, with markdown support.

Example

[[Tax management@content#internal]]
group: finances
summary: <md>
# Support for markdown!
## Subtitle
List:
1. One
2. Two
3. Three

> This is a quote

| tables | also | work |
|--------|------|------|
| tables | also | work |
</md>

Ref

[[<name>@ref]]
...

ref$<name>

Declares a raw section that can be referenced throughout the entire documentation project.
Similar to a C-like macro replacement, a ref is evaluated during the pre-linting phase, raising errors for any missing declarations, duplicates, or incorrect usage. After replacement, the linter phase checks whether the substituted text is valid.

✏️ You do not need to specify a search path for finding each ref. The only requirement is that when running Amauta (e.g., amauta --render -i ./dist/docs/main.amauta -o dist/doc.html -theme default), the -i path must include all the Amauta files you want considered. Amauta will automatically scan all files within this “root” path, filtering only the supported extensions (.amauta, .txt, .md).

Amauta will ignore any file that does not meet these conditions (correct location and supported extension). If you find otherwise, please report a bug on the official GitHub issues page.

You can also review how Amauta’s official documentation uses this feature by visiting the docs folder structure on GitHub.

Example

-- ./main.amauta
[[@tags]]
ref$my-tags

-- ./inner_folder/about.amauta
[[my-tags@ref]]
public#ffff00: Public asset.
private#ff00ff: Private asset.
deprecated#00ffff: Resource no longer in use.

-- Internally, during pre-linting, this evaluates to:
[[@tags]]
public#ffff00: Public asset.
private#ff00ff: Private asset.
deprecated#00ffff: Resource no longer in use.