{"id":30873723,"url":"https://github.com/ricoledan/guardrail-service-docs","last_synced_at":"2025-09-07T23:49:51.244Z","repository":{"id":310938735,"uuid":"1041763195","full_name":"Ricoledan/guardrail-service-docs","owner":"Ricoledan","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-21T04:27:34.000Z","size":26,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-21T06:49:14.730Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Handlebars","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Ricoledan.png","metadata":{"files":{"readme":"README.adoc","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-21T01:19:55.000Z","updated_at":"2025-08-21T04:27:37.000Z","dependencies_parsed_at":"2025-08-21T06:49:19.451Z","dependency_job_id":"f502162b-317f-458a-8c81-20cfbb92e5cb","html_url":"https://github.com/Ricoledan/guardrail-service-docs","commit_stats":null,"previous_names":["ricoledan/guardrail-service-docs"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Ricoledan/guardrail-service-docs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ricoledan%2Fguardrail-service-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ricoledan%2Fguardrail-service-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ricoledan%2Fguardrail-service-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ricoledan%2Fguardrail-service-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ricoledan","download_url":"https://codeload.github.com/Ricoledan/guardrail-service-docs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ricoledan%2Fguardrail-service-docs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274113047,"owners_count":25224334,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-07T02:00:09.463Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-07T23:49:47.710Z","updated_at":"2025-09-07T23:49:51.221Z","avatar_url":"https://github.com/Ricoledan.png","language":"Handlebars","funding_links":[],"categories":[],"sub_categories":[],"readme":"= Guardrail Service Documentation Repository\n:toc: left\n:toclevels: 3\n:icons: font\n:source-highlighter: highlight.js\n\nThis repository contains the Antora documentation component for the Guardrail Service.\n\n== Quick Start\n\n=== Prerequisites\n\n* Node.js 18+ and npm 8+\n* Git\n* (Optional) Nix with flakes enabled for reproducible development environment\n\n=== Local Development\n\n==== Option 1: Using Nix (Recommended)\n\n[source,bash]\n----\n# Enter the Nix development environment\nnix develop\n\n# Install Node dependencies\nnpm ci\n\n# Build documentation locally\nnpm run build:local\n\n# Preview documentation\nnpm run preview\n----\n\n==== Option 2: Using Node.js directly\n\n[source,bash]\n----\n# Install dependencies\nnpm ci\n\n# Build documentation locally\nnpm run build:local\n\n# Preview documentation\nnpm run preview\n----\n\nThe documentation will be available at http://localhost:8080\n\n=== Testing as an Antora Component\n\nThis repository is designed to be consumed by other Antora documentation sites. To test locally:\n\n[source,bash]\n----\nnpx antora local-antora-playbook.yml\nnpx http-server build\n----\n\n== Repository Structure\n\nThis follows the standard Antora component structure:\n\n[source,tree]\n----\nguardrail-service-docs/\n├── antora.yml                    # Component descriptor\n├── antora-playbook.yml          # Production build configuration\n├── local-antora-playbook.yml    # Local testing configuration\n├── modules/                      # Documentation modules\n│   ├── ROOT/                    # Main documentation module\n│   │   ├── nav.adoc            # Navigation for ROOT module\n│   │   ├── pages/              # Documentation pages\n│   │   ├── images/             # Images and diagrams\n│   │   ├── examples/           # Code examples\n│   │   └── attachments/        # Downloadable files\n│   ├── user-guide/             # User guide module\n│   ├── api/                    # API documentation module\n│   ├── admin/                  # Administration guide module\n│   └── developer/              # Developer documentation module\n├── supplemental-ui/             # UI customizations\n├── flake.nix                   # Nix flake for dev environment\n├── package.json                # Node.js dependencies and scripts\n└── Makefile                    # Convenience commands\n----\n\n== Available Commands\n\n=== npm Scripts\n\n[cols=\"2,3\"]\n|===\n|Command |Description\n\n|`npm run build:local`\n|Build documentation for local testing\n\n|`npm run build`\n|Build documentation for production\n\n|`npm run preview`\n|Build and preview documentation locally\n\n|`npm run serve`\n|Serve already built documentation\n\n|`npm run validate`\n|Validate cross-references and structure\n\n|`npm run watch`\n|Watch for changes and rebuild automatically\n\n|`npm run lint`\n|Lint AsciiDoc and YAML files\n\n|`npm run format`\n|Format JSON, YAML, and Markdown files\n\n|`npm run test`\n|Run validation and linting\n\n|`npm run clean`\n|Remove build artifacts\n|===\n\n=== Make Commands\n\nRun `make help` to see all available make commands:\n\n[source,bash]\n----\nmake help         # Show help message\nmake dev          # One-stop development setup\nmake build-local  # Build documentation locally\nmake preview      # Build and preview documentation\nmake validate     # Validate documentation structure\nmake clean        # Clean build artifacts\n----\n\n== Content Guidelines\n\n=== Writing Documentation\n\n* All documentation must be in AsciiDoc format (`.adoc` files)\n* Follow Antora page and navigation conventions\n* Use proper cross-references: `xref:module:page.adoc[Link Text]`\n* Place images in the module's `images/` directory\n* Include appropriate metadata and attributes\n\n=== Page Structure\n\nEvery page should include:\n\n[source,asciidoc]\n----\n= Page Title\n:description: Brief description of the page\n:keywords: comma, separated, keywords\n\nPage content starts here...\n----\n\n=== Cross-References\n\n* Within same module: `xref:page.adoc[Link Text]`\n* To another module: `xref:module:page.adoc[Link Text]`\n* To specific section: `xref:page.adoc#section-id[Link Text]`\n\n=== Adding Images\n\n[source,asciidoc]\n----\nimage::image-name.png[Alt text]\n\n// For diagrams\n[plantuml, diagram-name, svg]\n----\n@startuml\n...\n@enduml\n----\n----\n\n== Version Management\n\n=== Branch Strategy\n\n* `main` - Latest development version\n* `v1.x` - Version 1.x maintenance branch\n* `v2.x` - Version 2.x maintenance branch\n\n=== Version Configuration\n\nComponent version is defined in `antora.yml`:\n\n[source,yaml]\n----\nversion: ~           # Uses branch name as version\ndisplay_version: Latest  # Display name in UI\n----\n\n== Testing\n\n=== Local Testing\n\nTest the documentation locally before pushing:\n\n[source,bash]\n----\n# Validate structure\nnpm run validate\n\n# Check for broken links\nnpm run check-links\n\n# Lint content\nnpm run lint\n----\n\n=== CI/CD Pipeline\n\nThe GitLab CI pipeline automatically:\n\n. Validates documentation structure\n. Checks for broken links\n. Builds documentation\n. Deploys to GitLab Pages (main branch only)\n\n== Integration with Other Sites\n\nThis component can be consumed by other Antora documentation sites. Add to their playbook:\n\n[source,yaml]\n----\ncontent:\n  sources:\n  - url: https://gitlab.com/yourorg/guardrail-service/guardrail-service-docs.git\n    branches: [main, v1.x, v2.x]\n    start_path: .\n----\n\n== Customization\n\n=== UI Customizations\n\nPlace custom UI files in `supplemental-ui/`:\n\n* `supplemental-ui/partials/header-content.hbs` - Custom header\n* `supplemental-ui/partials/footer-content.hbs` - Custom footer\n* `supplemental-ui/css/custom.css` - Custom styles\n\n=== Build Customization\n\nModify playbooks to customize the build:\n\n* `local-antora-playbook.yml` - Local build settings\n* `antora-playbook.yml` - Production build settings\n\n== Troubleshooting\n\n=== Common Issues\n\n[cols=\"1,2\"]\n|===\n|Issue |Solution\n\n|`node_modules` not found\n|Run `npm ci` to install dependencies\n\n|Build fails with \"xref not found\"\n|Check cross-references with `npm run validate`\n\n|Changes not showing in preview\n|Clear cache with `npm run clean` then rebuild\n\n|Nix shell not loading\n|Ensure direnv is allowed: `direnv allow`\n\n|Port 8080 already in use\n|Change port in package.json or use different command\n|===\n\n=== Debug Mode\n\nEnable verbose output for debugging:\n\n[source,bash]\n----\nANTORA_LOG_LEVEL=debug npm run build:local\n----\n\n== Contributing\n\n=== Contribution Guidelines\n\n. Fork the repository\n. Create a feature branch\n. Make your changes\n. Validate your changes: `npm run test`\n. Submit a merge request\n\n=== Style Guide\n\n* Use sentence case for headings\n* Keep paragraphs concise\n* Include examples where appropriate\n* Add cross-references to related topics\n\n== Support\n\n* Issue Tracker: https://gitlab.com/yourorg/guardrail-service/guardrail-service-docs/issues\n* Documentation: https://yourorg.gitlab.io/guardrail-service/guardrail-service-docs\n* Main Project: https://gitlab.com/yourorg/guardrail-service\n\n== License\n\nThis documentation is licensed under the MIT License. See LICENSE file for details.\n\n== Resources\n\n* https://docs.antora.org[Antora Documentation]\n* https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[AsciiDoc Syntax Reference]\n* https://gitlab.com/antora/antora[Antora on GitLab]","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fricoledan%2Fguardrail-service-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fricoledan%2Fguardrail-service-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fricoledan%2Fguardrail-service-docs/lists"}