eAkta Documentation

Technical and product documentation for the eAkto citizen journey platform. The documentation site is built with MkDocs and uses a custom eAkto theme.

Run locally

Requirements

• Python 3.10 or later
• pip

Setup

Create and activate a virtual environment:

python -m venv .venv
.\.venv\Scripts\Activate.ps1

Install MkDocs:

python -m pip install -r docs/requirements.txt

Start the development server:

mkdocs serve

Open http://127.0.0.1:8000/ in a browser. MkDocs automatically rebuilds the site when a documentation or theme file changes.

Build

Generate the production site with strict validation:

mkdocs build --strict

The generated website is written to site/.

site/ is a build artifact. Edit the Markdown, theme, and configuration sources instead of editing generated HTML directly.

Build the PDF manual

Generate the searchable documentation manual and copy it into the site's download assets:

python tools/build_pdf.py

The archival copy is written to output/pdf/eakto-documentation.pdf. The website serves the matching copy from docs/assets/downloads/eakto-documentation.pdf.

Project structure

eAkta-docs/
├── docs/                  # Markdown pages and static assets
│   ├── assets/            # Fonts, images, JavaScript, and stylesheets
│   ├── api/               # API reference
│   ├── architecture/      # System architecture
│   ├── development/       # Contributor documentation
│   ├── getting-started/   # Installation and setup
│   ├── guides/            # Product and feature guides
│   ├── operations/        # Deployment, security, and troubleshooting
│   ├── project/           # Project scope and hackathon information
│   └── reference/         # Configuration, references, and glossary
├── docs_theme/            # Custom MkDocs Jinja theme
├── mkdocs.yml             # Site configuration and navigation
└── site/                  # Generated output; do not edit

Authoring

1. Add or update Markdown files under docs/.
2. Update nav in mkdocs.yml when adding a page.
3. Preview the result with mkdocs serve.
4. Run mkdocs build --strict before publishing.

The custom page template is docs_theme/main.html. Site styling and behavior are located under docs/assets/.

Deployment

The site is intended to be deployed with GitHub Pages. After GitHub Pages is configured for the repository, deploy the current branch with:

mkdocs gh-deploy --strict

This builds the documentation and publishes the generated output to the gh-pages branch.

Related repository

Application source: Sisig-Mayo/eActo