gitlab-docs-publishing

GitLab Docs Publishing

Publish styled HTML design docs on GitLab Pages and let reviewers file in-context feedback by selecting any text and clicking a floating 💬 bubble — which opens a pre-filled GitLab Issue in a new tab. Zero external services, zero in-page API calls.

Standalone HTML design docs are great for reading but miss two things GitLab does not provide out of the box: a public URL (GitLab renders .html blobs as source code, not as a page) and an in-context comment thread tied to the exact piece of prose a reviewer wants to discuss. This skill bolts both on using only free GitLab features:

GitLab Pages auto-publishes HTML on every merge to main.
Selection-driven 💬 bubble — a small JS widget watches text selection. On click, it navigates the browser to GitLab's "New issue" page with title
- description + label prefilled. GitLab authenticates the user with their existing session cookie.

When to Apply

Publishing a technical design doc (HTML or Markdown) for team review.
Teammates complain they have to git clone to see the styled HTML version.
Meeting feedback gets lost because there's no place to write it against specific sentences.
An HTML visual doc has been generated from source Markdown and now needs a distribution channel with feedback affordances.

Not for:

Documents that belong in GitLab Wiki (Wiki renders Markdown natively and has built-in comments).
Single-reviewer review — use MR line comments instead.
External/public audiences who do not have GitLab accounts.

How It Works

docs/<v>/foo.html
   │
   │ inject-comments.py:
   │   1. Strip any pre-existing in-page widgets
   │   2. Add ids to headings/figures/tables
   │   3. Inject <link>+<script> for the selection-bubble widget
   │   4. Copy comment-widget.{js,css} into <assets-dir>
   ↓
public/<v>/index.html  ──▶  GitLab Pages CI publishes public/
                              ↓
                     Reviewer opens published URL
                     Selects any text → 💬 bubble appears
                     Clicks → new tab on GitLab issues/new
                     with title + description + label prefilled
                     GitLab uses existing session cookie
                     Reviewer types → submits → labelled Issue created

Usage

Step 1 — Add the Pages CI job

Copy templates/gitlab-ci-pages.yml into your project's .gitlab-ci.yml and replace <VERSION> / <MAIN_HTML>. The template already runs the inject step (Step 2 explains its config). After merge to main, the doc is served at the project's Pages URL — check Settings → Pages for the exact host.

Step 2 — Configure the per-page Issue settings

Commit a small per-page config:

// docs/v1.0.0/comments-issue.json
{
  "gitlabHost": "https://gitlab.example.com",
  "projectPath": "group/subgroup/project",
  "pageUrl": "https://<pages-url>/v1.0.0/",
  "titlePrefix": "[v1.0.0-tech-design]",
  "issueLabels": "doc-comments"
}

The CI template invokes the injector with this config. The injector:

Adds id attributes to every <h1>–<h6> (slug from heading text), <div class="diagram-frame"> (figure-N), and <div class="aws-table-wrap"> (table-N) so anchor URLs resolve.
Injects <link rel="stylesheet"> and <script defer> referencing the bundled widget assets.
Copies comment-widget.{js,css} into --assets-dir.
Is idempotent — re-running on the same HTML doesn't double up.

Step 3 — Validate before publishing

python3 scripts/validate-html.py docs/v1.0.0/tech-design.html

Confirms tag balance and that anchor IDs are present.

What the reviewer sees

The published doc renders normally — no extra buttons or chrome anywhere.
Selecting any text shows a small orange "💬 添加评论" / "💬 Add comment" bubble above the selection.
Clicking opens a new tab on GitLab's New Issue page. Title is [<prefix>] §<heading-text> · "<first 30 chars of selection>…". Description contains an anchor link (back to the section) plus the selection quote, plus a hidden anchor JSON block for forward-compat tooling.
The reviewer types their comment under "Your comment:" and submits.

Deployment Checklist

HTML generated; tag balance and anchors validated.
.gitlab-ci.yml includes the pages job and the inject step.
comments-issue.json is committed and has the right gitlabHost, projectPath, and pageUrl.
Selecting text on the published page shows the bubble.
Clicking the bubble opens GitLab's New Issue page with prefilled title, description, and label.
After submitting, the resulting Issue has a working anchor link in its description that scrolls back to the right section.

About this skill