Merge pull request #26 from LibreSign/docs/github-pages-documentation

Add tested user documentation site and GitHub Pages deployment

Author: vitormattos

.docker/Dockerfile

@@ -7,9 +7,15 @@ ARG UID=1000
 ARG GID=1000
 
 RUN apt-get update \
-    && apt-get install -y --no-install-recommends git unzip zip bash curl ca-certificates \
+    && apt-get install -y --no-install-recommends git unzip zip bash curl ca-certificates python3 python3-pip python3-venv \
     && rm -rf /var/lib/apt/lists/*
 
+COPY docs/requirements-docs.txt /tmp/requirements-docs.txt
+
+RUN python3 -m venv /opt/docs-venv \
+    && /opt/docs-venv/bin/pip install --no-cache-dir -r /tmp/requirements-docs.txt \
+    && ln -sf /opt/docs-venv/bin/mkdocs /usr/local/bin/mkdocs
+
 RUN pecl install xdebug \
     && docker-php-ext-enable xdebug
 

.github/.performance/baseline.json

@@ -0,0 +1,16 @@
+{
+  "version": "1.0.0",
+  "created_at": "2026-06-01",
+  "allowed_regression_pct": 25.0,
+  "stale_threshold_pct": 35.0,
+  "benchmarks": {
+    "LibreSign\\XObjectTemplate\\Benchmarks\\CompilerBench::benchSimpleHtml": {
+      "mean": 0.356085,
+      "memory_real": 768
+    },
+    "LibreSign\\XObjectTemplate\\Benchmarks\\CompilerBench::benchComplexHtml": {
+      "mean": 1.366,
+      "memory_real": 1024
+    }
+  }
+}

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -9,12 +9,14 @@ body:
     id: summary
     attributes:
       label: Summary
+      description: Provide a short, objective problem statement.
     validations:
       required: true
   - type: textarea
     id: steps
     attributes:
       label: Steps to reproduce
+      description: Include exact input and commands.
     validations:
       required: true
   - type: textarea
@@ -23,3 +25,14 @@ body:
       label: Expected behavior
     validations:
       required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+    validations:
+      required: true
+  - type: input
+    id: runtime
+    attributes:
+      label: Runtime details
+      placeholder: PHP version, package version/commit, OS

.github/ISSUE_TEMPLATE/config.yml

@@ -6,3 +6,6 @@ contact_links:
   - name: Security disclosure
     url: https://github.com/LibreSign/xobject-template/security
     about: Please report vulnerabilities privately.
+  - name: Sponsor maintenance
+    url: https://github.com/sponsors/LibreSign
+    about: Funding helps prioritize fixes and compatibility work.

.github/ISSUE_TEMPLATE/documentation.yml

@@ -0,0 +1,23 @@
+# SPDX-FileCopyrightText: 2026 LibreSign
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+name: Documentation
+description: Report documentation errors or suggest improvements
+labels: [documentation]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What is unclear or incorrect?
+    validations:
+      required: true
+  - type: input
+    id: page
+    attributes:
+      label: Affected page/path
+      placeholder: docs/reference/supported-svg.md
+  - type: textarea
+    id: suggestion
+    attributes:
+      label: Suggested improvement
+      description: Keep suggestions objective and user-focused.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -9,11 +9,18 @@ body:
     id: problem
     attributes:
       label: Problem statement
+      description: Describe the user or integration problem first.
     validations:
       required: true
   - type: textarea
     id: proposal
     attributes:
       label: Proposed solution
+      description: Keep scope explicit and include expected API/behavior impact.
     validations:
       required: true
+  - type: textarea
+    id: non_goals
+    attributes:
+      label: Non-goals / out of scope
+      description: Clarify what should not be included.

.github/ISSUE_TEMPLATE/rendering_bug.yml

@@ -0,0 +1,72 @@
+# SPDX-FileCopyrightText: 2026 LibreSign
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+name: Rendering bug
+description: Report a minimal reproducible rendering issue for HTML/CSS/SVG to XObject output
+labels: [bug, rendering]
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: Describe the rendering issue in one or two sentences.
+    validations:
+      required: true
+  - type: textarea
+    id: minimal_input
+    attributes:
+      label: Minimal HTML/CSS/SVG input
+      description: Paste the smallest possible input that reproduces the issue.
+      render: markdown
+    validations:
+      required: true
+  - type: textarea
+    id: expected_output
+    attributes:
+      label: Expected output
+    validations:
+      required: true
+  - type: textarea
+    id: actual_output
+    attributes:
+      label: Actual output
+    validations:
+      required: true
+  - type: textarea
+    id: payload_details
+    attributes:
+      label: Generated content stream/resources (if possible)
+      description: Include compile result content stream/resources snippet when available.
+  - type: dropdown
+    id: affected_area
+    attributes:
+      label: Affected area
+      options:
+        - text
+        - PNG/JPEG
+        - SVG
+        - layout
+        - CSS
+        - interpolation
+        - placement
+    validations:
+      required: true
+  - type: input
+    id: php_version
+    attributes:
+      label: PHP version
+      placeholder: '8.2.x'
+    validations:
+      required: true
+  - type: input
+    id: package_version
+    attributes:
+      label: Package version or commit
+      placeholder: 'composer version, tag, or commit hash'
+    validations:
+      required: true
+  - type: textarea
+    id: fixture
+    attributes:
+      label: Minimal fixture attachment details
+      description: If possible, attach or describe a minimal fixture file set.

.github/PULL_REQUEST_TEMPLATE.md

@@ -10,11 +10,24 @@
 - [ ] Tests added/updated
 - [ ] Relevant checks executed
 
+## Documentation
+
+- [ ] Documentation updated
+- [ ] Examples updated if public behavior changed
+- [ ] Supported HTML/CSS/SVG matrix updated if relevant
+- [ ] Documentation drift checks pass
+
 ## Performance
 
 - [ ] Performance impact assessed
 - [ ] Benchmark threshold still green
 
+## Output integrity
+
+- [ ] No unsupported feature documented as supported
+- [ ] No generated build artifacts committed to the source branch
+- [ ] LibreSign use case impact considered if relevant
+
 ## Compliance
 
 - [ ] DCO sign-off in all commits

.github/workflows/docs.yml

@@ -0,0 +1,35 @@
+# SPDX-FileCopyrightText: 2026 LibreSign
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+name: docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+
+permissions:
+  contents: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install docs dependencies
+        run: pip install -r docs/requirements-docs.txt
+
+      - name: Deploy to gh-pages
+        run: mkdocs gh-deploy --force --config-file docs/mkdocs.yml