Docs viewer

AdminSuite includes a built-in docs viewer at:

  • /docs (relative to the mount path)

It renders Markdown (.md) files from a folder on your host app filesystem.

For an engine mounted at /internal/admin, its built-in viewer route is /internal/admin/docs.

Configuring the docs root (config.docs_path)

Generic gem default (reference, not the TechWright authoring destination):

  • AdminSuite.config.docs_path = Rails.root.join("docs")

For a host using the generated-artifact mode above, configure the output root explicitly:

AdminSuite.configure do |config|
  config.docs_path = Rails.root.join("generated", "admin_docs")
end

Or compute per-request:

AdminSuite.configure do |config|
  config.docs_path = ->(_controller) { Rails.root.join("generated", "admin_docs") }
end

If you want a persistent docs link in the AdminSuite sidebar, set:

AdminSuite.configure do |config|
  config.docs_url = "/internal/admin/docs"
end

This can also point to external docs.

Organization

Docs are grouped by their first folder name. For example:

  • <configured-root>/ops/runbooks.md → group “Ops”
  • <configured-root>/api/authentication.md → group “API”
  • <configured-root>/getting_started.md → group “Docs”

Security notes

The docs viewer defends against path traversal:

  • Rejects any path containing ..
  • Requires a .md extension
  • Resolves realpaths and ensures the requested file stays under the docs root