diff --git a/.github/workflows/stitchmd.yml b/.github/workflows/stitchmd.yml
new file mode 100644
index 0000000..b8da178
--- /dev/null
+++ b/.github/workflows/stitchmd.yml
@@ -0,0 +1,36 @@
+name: Stitch README.md
+
+on:
+ push:
+ branches: [main]
+
+ # Change the event to pull_request_target
+ # so that it runs in the context of the base repository.
+ pull_request_target:
+
+jobs:
+ stitchmd:
+ name: ${{ github.event_name == 'pull_request_target' && 'Update' || 'Check' }}
+ runs-on: ubuntu-latest
+
+ permissions:
+ contents: write
+
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ repository: ${{ github.event.pull_request.head.repo.full_name }}
+ ref: ${{ github.head_ref }}
+
+ - name: Check or update README
+ uses: abhinav/stitchmd-action@v1
+ with:
+ mode: ${{ github.event_name == 'pull_request_target' && 'write' || 'check' }}
+ summary: doc/README.md
+ output: README.md
+
+ - uses: stefanzweifel/git-auto-commit-action@v5
+ if: ${{ github.event_name == 'pull_request_target' }}
+ with:
+ file_pattern: README.md
+ commit_message: 'Update README.md'
diff --git a/README.md b/README.md
index 3167dcb..039692c 100644
--- a/README.md
+++ b/README.md
@@ -1,21 +1,33 @@
# goldmark-mermaid
+- [Introduction](#introduction)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Rendering methods](#rendering-methods)
+- [License](#license)
+
+## Introduction
+
[](https://pkg.go.dev/go.abhg.dev/goldmark/mermaid)
-[](https://github.com/abhinav/goldmark-mermaid/actions/workflows/go.yml)
+[](https://github.com/abhinav/goldmark-mermaid/actions/workflows/ci.yml)
[](https://codecov.io/gh/abhinav/goldmark-mermaid)
-goldmark-mermaid is an extension for the [goldmark] Markdown parser that adds
-support for [Mermaid] diagrams.
-
- [goldmark]: http://github.com/yuin/goldmark
- [Mermaid]: https://mermaid-js.github.io/mermaid/
+goldmark-mermaid is an extension for the [goldmark](http://github.com/yuin/goldmark) Markdown parser that adds
+support for [Mermaid](https://mermaid-js.github.io/mermaid/) diagrams.
**Demo**:
A web-based demonstration of the extension is available at
-.
+https://abhinav.github.io/goldmark-mermaid/demo/.
+
+### Features
+
+- Client-side rendering by injecting JavaScript
+- Server-side rendering with the Mermaid CLI
## Installation
+Install the latest version of the library with Go modules.
+
```bash
go get go.abhg.dev/goldmark/mermaid@latest
```
@@ -29,9 +41,7 @@ import "go.abhg.dev/goldmark/mermaid"
```
Then include the `mermaid.Extender` in the list of extensions you build your
-[`goldmark.Markdown`] with.
-
- [`goldmark.Markdown`]: https://pkg.go.dev/github.com/yuin/goldmark#Markdown
+[`goldmark.Markdown`](https://pkg.go.dev/github.com/yuin/goldmark#Markdown) with.
```go
goldmark.New(
@@ -45,17 +55,19 @@ goldmark.New(
The package supports Mermaid diagrams inside fenced code blocks with the language `mermaid`. For example,
- ```mermaid
- graph TD;
- A-->B;
- A-->C;
- B-->D;
- C-->D;
- ```
+
+```mermaid
+graph TD;
+ A-->B;
+ A-->C;
+ B-->D;
+ C-->D;
+```
+
When you render the Markdown as HTML, these will be rendered into diagrams.
-## Rendering diagrams
+## Rendering methods
Mermaid diagrams can be rendered
at the time the file is processed ("server-side")
@@ -82,3 +94,7 @@ goldmark.New(
By default, goldmark-mermaid will pick between the two,
based on whether it was able to find the `mmdc` executable on your `$PATH`.
+
+## License
+
+This software is made available under the MIT license.
diff --git a/doc/README.md b/doc/README.md
new file mode 100644
index 0000000..fc2c3e4
--- /dev/null
+++ b/doc/README.md
@@ -0,0 +1,7 @@
+# goldmark-mermaid
+
+- [Introduction](intro.md)
+- [Installation](install.md)
+- [Usage](usage.md)
+- [Rendering methods](render.md)
+- [License](license.md)
diff --git a/doc/install.md b/doc/install.md
new file mode 100644
index 0000000..6b941d5
--- /dev/null
+++ b/doc/install.md
@@ -0,0 +1,7 @@
+# Installation
+
+Install the latest version of the library with Go modules.
+
+```bash
+go get go.abhg.dev/goldmark/mermaid@latest
+```
diff --git a/doc/intro.md b/doc/intro.md
new file mode 100644
index 0000000..06c161a
--- /dev/null
+++ b/doc/intro.md
@@ -0,0 +1,20 @@
+# Introduction
+
+[](https://pkg.go.dev/go.abhg.dev/goldmark/mermaid)
+[](https://github.com/abhinav/goldmark-mermaid/actions/workflows/ci.yml)
+[](https://codecov.io/gh/abhinav/goldmark-mermaid)
+
+goldmark-mermaid is an extension for the [goldmark] Markdown parser that adds
+support for [Mermaid] diagrams.
+
+ [goldmark]: http://github.com/yuin/goldmark
+ [Mermaid]: https://mermaid-js.github.io/mermaid/
+
+**Demo**:
+A web-based demonstration of the extension is available at
+.
+
+## Features
+
+- Client-side rendering by injecting JavaScript
+- Server-side rendering with the Mermaid CLI
diff --git a/doc/license.md b/doc/license.md
new file mode 100644
index 0000000..75cf335
--- /dev/null
+++ b/doc/license.md
@@ -0,0 +1,3 @@
+# License
+
+This software is made available under the MIT license.
diff --git a/doc/render.md b/doc/render.md
new file mode 100644
index 0000000..20b3fb9
--- /dev/null
+++ b/doc/render.md
@@ -0,0 +1,27 @@
+# Rendering methods
+
+Mermaid diagrams can be rendered
+at the time the file is processed ("server-side")
+or in-browser when the file is viewed ("client-side").
+
+- With server-side rendering, goldmark-mermaid calls out to the
+ [MermaidJS CLI](https://github.com/mermaid-js/mermaid-cli)
+ to render SVGs inline into the document.
+- With client-side rendering, goldmark-mermaid generates HTML that
+ renders diagrams in-browser.
+
+You can pick between the two by setting `RenderMode` on `mermaid.Extender`.
+
+```go
+goldmark.New(
+ goldmark.WithExtensions(
+ &mermaid.Extender{
+ RenderMode: mermaid.RenderModeServer, // or RenderModeClient
+ },
+ ),
+ // ...
+).Convert(src, out)
+```
+
+By default, goldmark-mermaid will pick between the two,
+based on whether it was able to find the `mmdc` executable on your `$PATH`.
diff --git a/doc/usage.md b/doc/usage.md
new file mode 100644
index 0000000..36a5382
--- /dev/null
+++ b/doc/usage.md
@@ -0,0 +1,36 @@
+# Usage
+
+To use goldmark-mermaid, import the `mermaid` package.
+
+```go
+import "go.abhg.dev/goldmark/mermaid"
+```
+
+Then include the `mermaid.Extender` in the list of extensions you build your
+[`goldmark.Markdown`] with.
+
+ [`goldmark.Markdown`]: https://pkg.go.dev/github.com/yuin/goldmark#Markdown
+
+```go
+goldmark.New(
+ goldmark.WithExtensions(
+ // ...
+ &mermaid.Extender{},
+ ),
+ // ...
+).Convert(src, out)
+```
+
+The package supports Mermaid diagrams inside fenced code blocks with the language `mermaid`. For example,
+
+
+```mermaid
+graph TD;
+ A-->B;
+ A-->C;
+ B-->D;
+ C-->D;
+```
+
+
+When you render the Markdown as HTML, these will be rendered into diagrams.