ldraney/pal-enterprises
2
0
Fork 0
Code Issues 8 Pull requests Projects Releases Packages Wiki Activity Actions

Render docs/ markdown + mermaid at -docs URL #8

New issue
Open
opened 2026-05-09 18:23:34 +00:00 by forgejo_admin · 2 comments
forgejo_admin commented 2026-05-09 18:23:34 +00:00
Contributor
Copy link

Type

Feature

Lineage

Standalone — implements the -docs surface per convention-client-project-structure.

Repo

ldraney/pal-enterprises

User Story

As a client logged into pal-enterprises
I want to click my -docs link and see rendered project documentation with diagrams
So that I can reference my project docs without reading raw markdown on Forgejo

Context

Per convention-client-project-structure, every project gets a -docs surface behind Keycloak. The docs/ directory already exists in this repo with README.md, onboarding.md, architecture.md, and dashboards.md. Rails needs to be configured to render these markdown files (with mermaid diagram support) at a route. This is the dogfooding instance — pal-enterprises-docs serves platform docs to Lucas and clients.

File Targets

Files to create or modify:

  • app/controllers/docs_controller.rb — serves rendered markdown from docs/
  • app/views/docs/ — view templates for rendered docs
  • config/routes.rb — add /docs routes
  • Gemfile — add markdown rendering gem (e.g., redcarpet or commonmarker)

Files NOT to touch:

  • docs/ content files — already written, just need rendering

Acceptance Criteria

  • /docs route renders docs/README.md as the index
  • /docs/:slug renders individual doc files (e.g., /docs/architecture)
  • Mermaid diagrams in markdown render as diagrams (client-side JS)
  • Route is behind Keycloak auth (only authenticated users)
  • Navigation between docs pages works

Test Expectations

  • Integration test: authenticated user can access /docs
  • Integration test: unauthenticated user is redirected to login
  • Run command: bin/rails test

Constraints

  • Follow existing Rails patterns in the app
  • Mermaid rendering can be client-side (mermaid.js CDN)
  • Keep it simple — no database, just filesystem reads from docs/

Checklist

  • PR opened
  • Tests pass
  • No unrelated changes

Related

  • convention-client-project-structure — the convention requiring this surface
  • project-pal-enterprises
### Type Feature ### Lineage Standalone — implements the `-docs` surface per `convention-client-project-structure`. ### Repo `ldraney/pal-enterprises` ### User Story As a client logged into pal-enterprises I want to click my `-docs` link and see rendered project documentation with diagrams So that I can reference my project docs without reading raw markdown on Forgejo ### Context Per `convention-client-project-structure`, every project gets a `-docs` surface behind Keycloak. The `docs/` directory already exists in this repo with `README.md`, `onboarding.md`, `architecture.md`, and `dashboards.md`. Rails needs to be configured to render these markdown files (with mermaid diagram support) at a route. This is the dogfooding instance — pal-enterprises-docs serves platform docs to Lucas and clients. ### File Targets Files to create or modify: - `app/controllers/docs_controller.rb` — serves rendered markdown from `docs/` - `app/views/docs/` — view templates for rendered docs - `config/routes.rb` — add `/docs` routes - `Gemfile` — add markdown rendering gem (e.g., `redcarpet` or `commonmarker`) Files NOT to touch: - `docs/` content files — already written, just need rendering ### Acceptance Criteria - [ ] `/docs` route renders `docs/README.md` as the index - [ ] `/docs/:slug` renders individual doc files (e.g., `/docs/architecture`) - [ ] Mermaid diagrams in markdown render as diagrams (client-side JS) - [ ] Route is behind Keycloak auth (only authenticated users) - [ ] Navigation between docs pages works ### Test Expectations - [ ] Integration test: authenticated user can access /docs - [ ] Integration test: unauthenticated user is redirected to login - Run command: `bin/rails test` ### Constraints - Follow existing Rails patterns in the app - Mermaid rendering can be client-side (mermaid.js CDN) - Keep it simple — no database, just filesystem reads from `docs/` ### Checklist - [ ] PR opened - [ ] Tests pass - [ ] No unrelated changes ### Related - `convention-client-project-structure` — the convention requiring this surface - `project-pal-enterprises`
forgejo_admin commented 2026-05-09 18:57:22 +00:00
Author
Contributor
Copy link

Scope Review: NEEDS_REFINEMENT

Review note: review-1186-2026-05-09

Template is complete and file targets verified, but security and traceability gaps need attention before this moves to next_up.

Issues found:

  • [BODY] Missing security AC: No acceptance criterion for path traversal protection. The docs controller reads files from disk based on user-supplied slugs -- must reject traversal sequences like ../ and restrict slugs to [a-z0-9_-].
  • [BODY] Missing security constraint: Add slug sanitization requirement to Constraints section.
  • [BODY] Test infra gap: test/ directory does not exist in the repo. Test Expectations references bin/rails test but there is no test infrastructure to run. Note this in the ticket.
  • [SCOPE] arch note missing: arch-rails-app note does not exist in pal-e-docs. Create it.
  • [SCOPE] convention missing: convention-client-project-structure referenced in Context and Related does not exist in pal-e-docs. Create it or update the reference.
  • Mermaid AC unverifiable: No existing docs contain mermaid blocks, so AC #3 cannot be visually validated. Consider adding a sample mermaid diagram to one doc file.
## Scope Review: NEEDS_REFINEMENT Review note: `review-1186-2026-05-09` Template is complete and file targets verified, but security and traceability gaps need attention before this moves to next_up. **Issues found:** - `[BODY]` **Missing security AC**: No acceptance criterion for path traversal protection. The docs controller reads files from disk based on user-supplied slugs -- must reject traversal sequences like `../` and restrict slugs to `[a-z0-9_-]`. - `[BODY]` **Missing security constraint**: Add slug sanitization requirement to Constraints section. - `[BODY]` **Test infra gap**: `test/` directory does not exist in the repo. Test Expectations references `bin/rails test` but there is no test infrastructure to run. Note this in the ticket. - `[SCOPE]` **arch note missing**: `arch-rails-app` note does not exist in pal-e-docs. Create it. - `[SCOPE]` **convention missing**: `convention-client-project-structure` referenced in Context and Related does not exist in pal-e-docs. Create it or update the reference. - **Mermaid AC unverifiable**: No existing docs contain mermaid blocks, so AC #3 cannot be visually validated. Consider adding a sample mermaid diagram to one doc file.
forgejo_admin commented 2026-05-09 20:11:04 +00:00
Author
Contributor
Copy link

Closing — architecture changed. The -docs surface is a separate RoR repo, not a route within pal-enterprises. Replaced by a new ticket for creating the pal-enterprises-docs repo.

Closing — architecture changed. The `-docs` surface is a separate RoR repo, not a route within pal-enterprises. Replaced by a new ticket for creating the `pal-enterprises-docs` repo.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
522-payment-email-circuit-fee
add-kaniko-cache
fix-harbor-external-url
fix-kaniko-insecure-pull
fix-pipeline-image-pull
19-woodpecker-ci-pipeline
fix-dockerfile-build-tag
18-dockerfile-arch-migration
7-add-woodpecker-pipeline
No results found.
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
ldraney/pal-enterprises#8
No description provided.