gitlab-docs-publishing

Name: gitlab-docs-publishing
Author: aws-samples

37stars20forks

How to install gitlab-docs-publishing?

aws-samples/sample-agent-skills-for-builders/gitlab-docs-publishing

$npx -y skills add aws-samples/sample-agent-skills-for-builders --skill gitlab-docs-publishing

Installs into the current project.

Summary

Publish HTML/Markdown design documents on GitLab Pages with selection-driven discussion. Reviewers select any text in the published doc; a floating 💬 bubble opens a prefilled GitLab Issue (title + anchor link + selection quote + label) in a new tab. GitLab handles auth via the u

Files · 1

View on GitHub

SKILL.md

1	# GitLab Docs Publishing
2
3	Publish styled HTML design docs on GitLab Pages and let reviewers file
4	in-context feedback by selecting any text and clicking a floating 💬
5	bubble — which opens a pre-filled GitLab Issue in a new tab. Zero external
6	services, zero in-page API calls.
7
8	Standalone HTML design docs are great for reading but miss two things GitLab
9	does not provide out of the box: a public URL (GitLab renders `.html` blobs
10	as source code, not as a page) and an in-context comment thread tied to the
11	exact piece of prose a reviewer wants to discuss. This skill bolts both on
12	using only free GitLab features:
13
14	- GitLab Pages auto-publishes HTML on every merge to main.
15	- Selection-driven 💬 bubble — a small JS widget watches text selection.
16	On click, it navigates the browser to GitLab's "New issue" page with title
17	+ description + label prefilled. GitLab authenticates the user with their
18	existing session cookie.
19
20	## When to Apply
21
22	- Publishing a technical design doc (HTML or Markdown) for team review.
23	- Teammates complain they have to `git clone` to see the styled HTML version.
24	- Meeting feedback gets lost because there's no place to write it against
25	specific sentences.
26	- An HTML visual doc has been generated from source Markdown and now needs
27	a distribution channel with feedback affordances.
28
29	Not for:
30
31	- Documents that belong in GitLab Wiki (Wiki renders Markdown natively and
32	has built-in comments).
33	- Single-reviewer review — use MR line comments instead.
34	- External/public audiences who do not have GitLab accounts.
35
36	## How It Works
37
38	```
39	docs/<v>/foo.html
40	│
41	│ inject-comments.py:
42	│ 1. Strip any pre-existing in-page widgets
43	│ 2. Add ids to headings/figures/tables
44	│ 3. Inject <link>+<script> for the selection-bubble widget
45	│ 4. Copy comment-widget.{js,css} into <assets-dir>
46	↓
47	public/<v>/index.html ──▶ GitLab Pages CI publishes public/
48	↓
49	Reviewer opens published URL
50	Selects any text → 💬 bubble appears
51	Clicks → new tab on GitLab issues/new
52	with title + description + label prefilled
53	GitLab uses existing session cookie
54	Reviewer types → submits → labelled Issue created
55	```
56
57	## Usage
58
59	### Step 1 — Add the Pages CI job
60
61	Copy [`templates/gitlab-ci-pages.yml`](./templates/gitlab-ci-pages.yml) into
62	your project's `.gitlab-ci.yml` and replace `<VERSION>` / `<MAIN_HTML>`.
63	The template already runs the inject step (Step 2 explains its config).
64	After merge to main, the doc is served at the project's Pages URL — check
65	Settings → Pages for the exact host.
66
67	### Step 2 — Configure the per-page Issue settings
68
69	Commit a small per-page config:
70
71	```json
72	// docs/v1.0.0/comments-issue.json
73	{
74	"gitlabHost": "https://gitlab.example.com",
75	"projectPath": "group/subgroup/project",
76	"pageUrl": "https://<pages-url>/v1.0.0/",
77	"titlePrefix": "[v1.0.0-tech-design]",
78	"issueLabels": "doc-comments"
79	}
80	```
81
82	The CI template invokes the injector with this config. The injector:
83
84	- Adds `id` attributes to every `<h1>`–`<h6>` (slug from heading text),
85	`<div class="diagram-frame">` (`figure-N`), and `<div class="aws-table-wrap">`
86	(`table-N`) so anchor URLs resolve.
87	- Injects `<link rel="stylesheet">` and `<script defer>` referencing the
88	bundled widget assets.
89	- Copies `comment-widget.{js,css}` into `--assets-dir`.
90	- Is idempotent — re-running on the same HTML doesn't double up.
91
92	### Step 3 — Validate before publishing
93
94	```bash
95	python3 scripts/validate-html.py docs/v1.0.0/tech-design.html
96	```
97
98	Confirms tag balance and that anchor IDs are present.
99
100	### What the reviewer sees
101
102	- The published doc renders normally — no extra buttons or chrome anywhere.
103	- Selecting any text shows a small orange "💬 添加评论" / "💬 Add comment"
104	bubble above the selection.
105	- Clicking opens a new tab on GitLab's New Issue page. Title is
106	`[<prefix>] §<heading-text> · "<first 30 chars of selection>…"`.
107	Description contains an anchor link (back to the section) plus the
108	selection quote, plus a hidden anchor JSON block for forward-compat tooling.
109	- The reviewer types their comment under "Your comment:" and submits.
110
111	### Deployment Checklist
112
113	- [ ] HTML generated; tag balance and anchors validated.
114	- [ ] `.gitlab-ci.yml` includes the `pages` job and the inject step.
115	- [ ] `comments-issue.json` is committed and has the right `gitlabHost`,

People who liked this also viewed

6 picks

Type

gitlab-docs-publishing

37stars20forks

View on GitHub

How to install gitlab-docs-publishing?

aws-samples/sample-agent-skills-for-builders/gitlab-docs-publishing

$npx -y skills add aws-samples/sample-agent-skills-for-builders --skill gitlab-docs-publishing

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# GitLab Docs Publishing
2
3	Publish styled HTML design docs on GitLab Pages and let reviewers file
4	in-context feedback by selecting any text and clicking a floating 💬
5	bubble — which opens a pre-filled GitLab Issue in a new tab. Zero external
6	services, zero in-page API calls.
7
8	Standalone HTML design docs are great for reading but miss two things GitLab
9	does not provide out of the box: a public URL (GitLab renders `.html` blobs
10	as source code, not as a page) and an in-context comment thread tied to the
11	exact piece of prose a reviewer wants to discuss. This skill bolts both on
12	using only free GitLab features:
13
14	- GitLab Pages auto-publishes HTML on every merge to main.
15	- Selection-driven 💬 bubble — a small JS widget watches text selection.
16	On click, it navigates the browser to GitLab's "New issue" page with title
17	+ description + label prefilled. GitLab authenticates the user with their
18	existing session cookie.
19
20	## When to Apply
21
22	- Publishing a technical design doc (HTML or Markdown) for team review.
23	- Teammates complain they have to `git clone` to see the styled HTML version.
24	- Meeting feedback gets lost because there's no place to write it against
25	specific sentences.
26	- An HTML visual doc has been generated from source Markdown and now needs
27	a distribution channel with feedback affordances.
28
29	Not for:
30
31	- Documents that belong in GitLab Wiki (Wiki renders Markdown natively and
32	has built-in comments).
33	- Single-reviewer review — use MR line comments instead.
34	- External/public audiences who do not have GitLab accounts.
35
36	## How It Works
37
38	```
39	docs/<v>/foo.html
40	│
41	│ inject-comments.py:
42	│ 1. Strip any pre-existing in-page widgets
43	│ 2. Add ids to headings/figures/tables
44	│ 3. Inject <link>+<script> for the selection-bubble widget
45	│ 4. Copy comment-widget.{js,css} into <assets-dir>
46	↓
47	public/<v>/index.html ──▶ GitLab Pages CI publishes public/
48	↓
49	Reviewer opens published URL
50	Selects any text → 💬 bubble appears
51	Clicks → new tab on GitLab issues/new
52	with title + description + label prefilled
53	GitLab uses existing session cookie
54	Reviewer types → submits → labelled Issue created
55	```
56
57	## Usage
58
59	### Step 1 — Add the Pages CI job
60
61	Copy [`templates/gitlab-ci-pages.yml`](./templates/gitlab-ci-pages.yml) into
62	your project's `.gitlab-ci.yml` and replace `<VERSION>` / `<MAIN_HTML>`.
63	The template already runs the inject step (Step 2 explains its config).
64	After merge to main, the doc is served at the project's Pages URL — check
65	Settings → Pages for the exact host.
66
67	### Step 2 — Configure the per-page Issue settings
68
69	Commit a small per-page config:
70
71	```json
72	// docs/v1.0.0/comments-issue.json
73	{
74	"gitlabHost": "https://gitlab.example.com",
75	"projectPath": "group/subgroup/project",
76	"pageUrl": "https://<pages-url>/v1.0.0/",
77	"titlePrefix": "[v1.0.0-tech-design]",
78	"issueLabels": "doc-comments"
79	}
80	```
81
82	The CI template invokes the injector with this config. The injector:
83
84	- Adds `id` attributes to every `<h1>`–`<h6>` (slug from heading text),
85	`<div class="diagram-frame">` (`figure-N`), and `<div class="aws-table-wrap">`
86	(`table-N`) so anchor URLs resolve.
87	- Injects `<link rel="stylesheet">` and `<script defer>` referencing the
88	bundled widget assets.
89	- Copies `comment-widget.{js,css}` into `--assets-dir`.
90	- Is idempotent — re-running on the same HTML doesn't double up.
91
92	### Step 3 — Validate before publishing
93
94	```bash
95	python3 scripts/validate-html.py docs/v1.0.0/tech-design.html
96	```
97
98	Confirms tag balance and that anchor IDs are present.
99
100	### What the reviewer sees
101
102	- The published doc renders normally — no extra buttons or chrome anywhere.
103	- Selecting any text shows a small orange "💬 添加评论" / "💬 Add comment"
104	bubble above the selection.
105	- Clicking opens a new tab on GitLab's New Issue page. Title is
106	`[<prefix>] §<heading-text> · "<first 30 chars of selection>…"`.
107	Description contains an anchor link (back to the section) plus the
108	selection quote, plus a hidden anchor JSON block for forward-compat tooling.
109	- The reviewer types their comment under "Your comment:" and submits.
110
111	### Deployment Checklist
112
113	- [ ] HTML generated; tag balance and anchors validated.
114	- [ ] `.gitlab-ci.yml` includes the `pages` job and the inject step.
115	- [ ] `comments-issue.json` is committed and has the right `gitlabHost`,

People who liked this also viewed

6 picks

Type