Where to Find Apache Maka Documentation: Repository and Website Guide

Apache Maka documentation is centrally organized in docs/README.md within the repository, which serves as the authoritative hub linking to architecture guides, security policies, package-specific READMEs, and the rendered website at https://maka.apache.org.

The Apache Maka project maintains its documentation directly alongside the source code in the apache/maka repository. This approach ensures that documentation stays synchronized with implementation changes and provides multiple access paths for developers and contributors.

Primary Documentation Hub (docs/README.md)

The definitive starting point for all Apache Maka documentation is the docs/README.md file. This document functions as an authority map that links to every critical contract and guide within the project.

When you open docs/README.md, you will find structured links to:

• High-level architecture via ARCHITECTURE.md
• Product design rationale via DESIGN.md
• Security policies via SECURITY.md
• Package-specific documentation under packages/

All links in this hub point to the authoritative source inside the repo, ensuring the documentation never drifts from the actual code base.

Core Architectural and Design Documents

Beyond the main hub, several root-level markdown files provide deep technical context:

• ARCHITECTURE.md – Contains the high-level system map and component diagrams that explain how Maka's subsystems interact.
• DESIGN.md – Outlines the product design rationale, roadmap, and long-term vision for the project.
• SECURITY.md – Details the security model, threat analysis, and privacy context for deploying Maka safely.

These files represent the current contracts that govern the project's technical direction and security posture.

Package-Specific Documentation

For developers working with specific components, each package maintains its own README with targeted contracts and usage instructions:

• packages/runtime/README.md – Runtime package contracts and integration guides.
• packages/cli/README.md – Command-line interface usage and installation instructions.
• packages/ui/README.md – UI primitives and shared component documentation.

These documents are linked from the main docs/README.md hub and provide implementation-specific details that complement the high-level architecture.

Website and Rendered Documentation

The same documentation source is rendered for end-users at https://maka.apache.org/en/. The website provides a searchable, navigable version of the repository documentation, together with a downloadable PDF of the architecture if needed.

The source for the website build lives in website/README.md, which explains how the static site generator processes the markdown files from the docs/ directory.

Documentation Organization Structure

The docs/ folder follows a specific organizational pattern:

• docs/blogs/ – Holds long-form design essays and architectural decision records.
• docs/archive/ – Stores historic material that is no longer the source of truth but retained for reference.
• docs/ root – Contains current active contracts and authoritative guides.

Root and package READMEs describe stable public entry points and code ownership, while the docs/ directory houses the evolving technical specifications.

Programmatic Access to Documentation

You can access Apache Maka documentation programmatically from a local checkout or via direct HTTP requests.

Open the main documentation hub in your default browser:

# Linux/macOS

xdg-open https://github.com/apache/maka/blob/main/docs/README.md

Read the first lines of the hub file locally:

head -n 20 docs/README.md

Access documentation content in Node.js:

import { readFileSync } from 'fs';
const hub = readFileSync('docs/README.md', 'utf8');
console.log(hub.split('\n').slice(0, 10).join('\n'));

Retrieve specific architecture documents via HTTP:

import requests
url = "https://raw.githubusercontent.com/apache/maka/main/docs/architecture/runtime-host-architecture.md"
print(requests.get(url).text[:500])

Summary

• Main entry point: docs/README.md serves as the central authority map and index.
• Core contracts: ARCHITECTURE.md, DESIGN.md, and SECURITY.md provide high-level technical and security guidance.
• Package docs: Individual README.md files under packages/ contain component-specific instructions.
• Web presence: https://maka.apache.org offers the same content in a searchable format.
• Historical context: docs/archive/ contains superseded documentation for reference purposes.

Frequently Asked Questions

Where is the main entry point for Apache Maka documentation?

The primary entry point is docs/README.md in the repository root. This file contains links to all other documentation including architecture guides, security policies, and package-specific READMEs, ensuring you can navigate the entire documentation tree from a single location.

How do the repository docs differ from the website?

The repository documentation at https://github.com/apache/maka represents the authoritative source that is version-controlled alongside the code. The website at https://maka.apache.org renders the same markdown files into a searchable HTML format for easier reading, but both contain identical content.

How do I find documentation for a specific Maka package?

Navigate to the packages/ directory in the repository. Each subdirectory (such as packages/runtime, packages/cli, or packages/ui) contains its own README.md file with specific contracts, API documentation, and usage examples for that component.

Are there archived versions of the documentation available?

Yes. Historical documentation that is no longer current but retained for reference lives in docs/archive/. Current authoritative contracts reside in the root docs/ directory, while long-form design essays can be found in docs/blogs/.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}