akasharender

AkashaRender - Rendering engine for AkashaCMS

AkashaCMS is a collection of static website generation tools. The primary purpose is publishing websites, but a related set of tools called AkashaEPUB allows one to generate EPUB documents.

AkashaRender is the core tool for AkashaCMS/AkashaEPUB.

The available commands are:

Usage: akasharender [options] [command]

Options:
  -V, --version                            output the version number
  -h, --help                               display help for command

Commands:
  copy-assets <configFN>                   Copy assets into output directory
  document <configFN> <documentFN>         Show information about a document
  render-document <configFN> <documentFN>  Render a document into output directory
  render [options] <configFN>              Render a site into output directory
  validate-sitemap [options] <configFN>    Validate sitemap XML file against rendered 
                                           output directory
  check-ready [options] <configFN>         Verify that all files are loaded before 
                                           isReady triggers (diagnostic tool)
  explain <configFN>                       Explain a cache query
  watch <configFN>                         Track changes to files in a site, and rebuild
                                           anything that changes
  gh-pages-publish [options] <configFN>    Publish a site using Github Pages.  Takes the
                                           rendering destination, adds it into a branch,
                                           and pushes that to Github
  config <configFN>                        Print a site configuration
  docdirs <configFN>                       List the documents directories in a site
                                           configuration
  assetdirs <configFN>                     List the assets directories in a site
                                           configuration
  partialdirs <configFN>                   List the partials directories in a site
                                           configuration
  layoutsdirs <configFN>                   List the layouts directories in a site
                                           configuration
  documents <configFN>                     List the documents in a site configuration
  docinfo <configFN> <docFN>               Show information about a document in a site
                                           configuration
  tags <configFN>                          List the tags
  search [options] <configFN>              Search for documents
  assets <configFN>                        List the assets in a site configuration
  assetinfo <configFN> <docFN>             Show information about an asset in a site
                                           configuration
  layouts <configFN>                       List the layouts in a site configuration
  layoutinfo <configFN> <docFN>            Show information about a layout in a site
                                           configuration
  partials <configFN>                      List the partials in a site configuration
  partialinfo <configFN> <docFN>           Show information about a partial in a site
                                           configuration
  index [options] <configFN>               Loads configuration, indexes content, then 
                                           exits (use --verbose for summary)
  help [command]                           display help for command

The configuration file parameter, configFN, is the filename for a JavaScript file that sets up an AkashaRender configuration object.

The typical usage for the commands is with these package.json scripts:

 "scripts": {
    "prebuild": "akasharender copy-assets config.js",
    "build": "akasharender render config.js",
    "deploy": "cd out && rsync --archive --delete --verbose ./ user-name@example.com:example.com/ "
}

The model is to have several input directories, containing content and assets for the resulting website, and one output directory for the rendered website (or EPUB). The possible input directories are:

• assets -- Files that are simply copied and require no rendering
• documents -- Files that may require rendering, such as converting LESS to CSS, or Markdown/AsciiDoc to HTML
• partials -- Template snippets that can be used anywhere in a document
• layouts -- Page layout templates

The prebuild step uses copy-assets to copy files from the assets directory to the rendering directory. The build step then renders content from the documents directory to the rendering directory.

In this case the rendering directory is out, and the deploy step uses rsync to upload that directory to a webserver.

Diagnostic Commands

check-ready - Verify Cache Timing

The check-ready command is a diagnostic tool that verifies all files are loaded into the cache before the isReady event triggers. This helps ensure that rendering operations have access to the complete file list.

npx akasharender check-ready config.js [options]

Options:

• --verbose - Show detailed per-cache results
• --delay <ms> - Wait time in milliseconds to check for late additions (default: 2000)

The command:

1. Loads your site configuration
2. Records the number of files in each cache (documents, assets, layouts, partials)
3. Waits for the specified delay
4. Checks if any additional files appeared after the initial load
5. Reports success (exit code 0) or failure (exit code 1)

Example output:

Running isReady timing check...

✓ Setup completed in 113ms
  Documents: 80
  Assets: 3
  Layouts: 11
  Partials: 20

Waiting 2000ms to check for late additions...

Results:

✅ SUCCESS: No files added after isReady. Timing is correct.

All caches are stable:
  ✓ Documents: 80 files
  ✓ Assets: 3 files
  ✓ Layouts: 11 files
  ✓ Partials: 20 files

Use this command if you suspect files are being rendered before all content is loaded, or to verify cache timing in your CI/CD pipeline.

index - Load and Index Files

The index command loads your site configuration, indexes all content files, and exits. This is useful for verifying that your configuration is correct and all files are being found.

npx akasharender index config.js [--verbose]

Options:

• --verbose - Show detailed event tracking as files are added, plus summary

Example output with --verbose:

Indexing files with verbose output...

[ADDED] assets: file.txt
[ADDED] assets: file-virgin.txt
[ADDED] assets: rss_button.png
[READY] assets

[ADDED] partials: helloworld.html
[ADDED] partials: helloworld2.html
...
[READY] partials

[ADDED] layouts: default.html.ejs
...
[READY] layouts

[ADDED] documents: index.html.md
[ADDED] documents: page1.html.md
...
[READY] documents

✓ Indexing completed in 105ms

=== Summary ===
Documents: 80 files
Assets: 3 files
Layouts: 11 files
Partials: 20 files
Total: 114 files

The verbose mode shows:

• [ADDED] events as each file is found and indexed
• [READY] events when each cache type completes indexing
• [ERROR] events if any files fail to process
• Final summary with counts and timing

Without --verbose, the command runs silently, which is useful in scripts where you only want to verify the configuration loads correctly.

Use this command to:

• Verify your configuration is valid
• See exactly which files are being indexed
• Watch the indexing process in real-time
• Debug missing or unexpected files
• Measure how long indexing takes
• Test configuration changes before rendering

validate-sitemap - Validate Sitemap Against Rendered Output

The validate-sitemap command validates your generated sitemap XML file against the actual rendered output directory. It ensures that every URL in the sitemap corresponds to a file that exists in your output directory.

npx akasharender validate-sitemap config.js [options]

Options:

• --sitemap <filename> - Sitemap filename relative to output directory (default: sitemap.xml)
• --strict - Exit with error code 1 if validation fails (useful for CI/CD)
• --json - Output results as JSON instead of human-readable text

The command validates:

1. XML Structure - Checks for correct XML format, namespace, and required elements
2. File Existence - Verifies each URL in the sitemap maps to an actual file in the output directory
3. URL Mapping - Ensures URLs match your site's base URL and follow correct conventions

Example output:

Sitemap Validation Report
=========================

Sitemap: out/sitemap.xml
Total Entries: 150
Valid Entries: 148
Invalid Entries: 2

Missing Files:
  ✗ out/blog/old-post.html
    URL: https://example.com/blog/old-post.html
  ✗ out/projects/archived.html
    URL: https://example.com/projects/archived.html

XML Validation: ✓ Valid
  - Namespace: ✓ Correct
  - Well-formed: ✓ Yes

Summary: ✗ Validation failed: 2 invalid entries, 0 errors

JSON output (--json):

npx akasharender validate-sitemap config.js --json > validation-report.json

This produces a structured JSON report suitable for parsing in CI/CD pipelines or custom tooling.

Strict mode for CI/CD:

# Fails build if sitemap has invalid entries
npx akasharender validate-sitemap config.js --strict

Validate custom sitemap:

# For sites with multiple sitemaps
npx akasharender validate-sitemap config.js --sitemap blog-sitemap.xml

Use this command to:

• Catch broken links before deployment
• Verify sitemap accuracy after site builds
• Integrate sitemap validation into CI/CD pipelines
• Debug why pages aren't appearing in search engines
• Ensure sitemap stays synchronized with rendered content

Common issues detected:

• Files referenced in sitemap but not rendered (deleted or renamed pages)
• Incorrect base URLs (wrong domain in sitemap entries)
• Malformed sitemap XML (missing namespace, invalid structure)
• Directory URLs not mapping to index.html correctly

CI/CD Integration Example:

# GitHub Actions
- name: Build site
  run: npx akasharender render config.js

- name: Validate sitemap
  run: npx akasharender validate-sitemap config.js --strict --json > validation.json

- name: Upload validation report
  uses: actions/upload-artifact@v3
  with:
    name: sitemap-validation
    path: validation.json

AkashaCMS Plugins

AkashaCMS plugins extend the capabilities of the system.

For more information see:

• Project website: https://akashacms.com
• Source for project website: https://github.com/akashacms/akashacms-website
• Example repository: https://github.com/akashacms/akashacms-example
• Website matching the example: https://example.akashacms.com/