docs: document OGP image workflow

README.md

@@ -52,17 +52,45 @@ $ github-issue-cms generate --token="YOUR_GITHUB_TOKEN"
 > [!NOTE]
 > If your issues have images attached via drag-and-drop (`https://github.com/user-attachments/assets/...`) in a **private** repository, use a **classic** Personal Access Token. Fine-grained PATs and GitHub App installation tokens (including the Actions-provided `GITHUB_TOKEN`) are not accepted by GitHub's attachment download endpoint and will cause image downloads to fail with a 404.
 
-### Preview an OGP template
+### Generate OGP images
+
+Generate a 1200x630 JPEG for every generated article:
+
+```bash
+$ github-issue-cms generate --token="YOUR_GITHUB_TOKEN" --with-ogimage
+```
+
+Images are saved next to their Markdown article. A page bundle receives
+`ogp.jpeg`; a flat Markdown file such as `post.md` receives `post.ogp.jpeg`.
+
+To generate an image for one local article, use `ogimage`:
+
+```bash
+$ github-issue-cms ogimage --file content/posts/2024-01-15_103000.md
+```
+
+This command writes `ogp.jpeg` to the configured image output directory.
+Both commands render HTML in headless Chromium. Chromium is downloaded
+automatically when needed, or set `GIC_CHROMIUM_BIN` to an installed browser.
+
+### Preview an OGP template in a browser
 
 Use the live preview server while editing a custom OGP template:
 
 ```bash
 $ github-issue-cms ogimage preview ogp.html
 ```
 
-Open `http://localhost:6140`. The template is rendered with sample article
-data in a fixed 1200x630 OGP viewport and reloads automatically when the file
-changes. Relative assets are served from the template's directory.
+Open `http://localhost:6140` in a browser. The template is rendered with
+sample article data in a fixed 1200x630 OGP viewport and reloads automatically
+when the file changes. Relative assets are served from the template's
+directory. Use `--port` or `--host` to change the server address.
+
+Pass the template to `ogimage` to generate an image with it:
+
+```bash
+$ github-issue-cms ogimage --file article.md --template ogp.html
+```
 
 If your repository has issues and attached images, they will be exported like this tree.
 

docs/content/_index.md

@@ -11,6 +11,7 @@ cascade:
 
 {{<cards>}}
     {{<card link="quickstart" icon="globe" title="Quick Start">}}
+    {{<card link="ogp-images" icon="image" title="OGP Images">}}
 {{</cards>}}
 
 ## {{<icon "chip">}} Configuration
@@ -19,4 +20,3 @@ cascade:
   {{<card link="configuration/parameters" title="gic.config.yaml reference" icon="code" >}}
   {{<card link="configuration/github-actions-integration" title="CI with GitHub Actions" icon="code" >}}
 {{</cards>}}
-

docs/content/ogp-images.md

@@ -0,0 +1,79 @@
+---
+title: 'OGP Images'
+weight: 2
+---
+
+`github-issue-cms` can render a 1200x630 JPEG Open Graph Protocol (OGP) image from article metadata.
+
+## Generate images with articles
+
+Add `--with-ogimage` when generating content.
+
+```shell
+$ github-issue-cms generate --token="YOUR_GITHUB_TOKEN" --with-ogimage
+```
+
+The command creates one OGP image for each generated article.
+
+For a page bundle (`index.md`), the image is saved as `ogp.jpeg` in the bundle directory.
+
+For a flat Markdown file, `post.md` becomes `post.ogp.jpeg` in the same directory.
+
+## Generate one image
+
+Use `ogimage` to render a local Markdown article.
+
+```shell
+$ github-issue-cms ogimage --file content/posts/2024-01-15_103000.md
+```
+
+This command writes `ogp.jpeg` to the image output directory configured in `gic.config.yaml`.
+
+The renderer uses headless Chromium.
+
+It downloads Chromium automatically when necessary.
+
+Set `GIC_CHROMIUM_BIN` to use an existing Chromium-compatible browser binary instead.
+
+## Customize the template
+
+Pass an HTML template with `--template`.
+
+```shell
+$ github-issue-cms ogimage --file article.md --template ogp.html
+```
+
+Templates use Go's `html/template` syntax and receive these values:
+
+- `.Title`
+- `.Author`
+- `.Date`
+- `.Category`
+- `.Tags`
+
+For example:
+
+```html
+<h1>{{ .Title }}</h1>
+{{ range .Tags }}<span>#{{ . }}</span>{{ end }}
+```
+
+## Preview a template in a browser
+
+Start the local preview server while editing the template.
+
+```shell
+$ github-issue-cms ogimage preview ogp.html
+```
+
+Open `http://localhost:6140` in a browser.
+
+The preview uses sample article data, displays the template in a fixed 1200x630 viewport, and reloads automatically after the template file changes.
+
+Relative URLs in the template are served from the template directory, so local CSS, images, and fonts can be previewed without copying them elsewhere.
+
+Use `--port` or `--host` when the default address is unavailable.
+
+```shell
+$ github-issue-cms ogimage preview ogp.html --port 8080
+```