README: Use stitchmd (#57)

Use stitchmd to put the README together. This will help make some of the upcoming changes easier.
abhinav · Nov 4, 2023 · 9383d1d · 9383d1d
1 parent 178efc0
commit 9383d1d
Show file tree

Hide file tree

Showing 8 changed files with 170 additions and 18 deletions.
diff --git a/.github/workflows/stitchmd.yml 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
@@ -1,21 +1,33 @@
 # goldmark-mermaid
 
+- [Introduction](#introduction)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Rendering methods](#rendering-methods)
+- [License](#license)
+
+## Introduction
+
 [![Go Reference](https://pkg.go.dev/badge/go.abhg.dev/goldmark/mermaid.svg)](https://pkg.go.dev/go.abhg.dev/goldmark/mermaid)
-[![Go](https://github.com/abhinav/goldmark-mermaid/actions/workflows/go.yml/badge.svg)](https://github.com/abhinav/goldmark-mermaid/actions/workflows/go.yml)
+[![CI](https://github.com/abhinav/goldmark-mermaid/actions/workflows/ci.yml/badge.svg)](https://github.com/abhinav/goldmark-mermaid/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/abhinav/goldmark-mermaid/branch/main/graph/badge.svg?token=W98KYF8SPE)](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/>.
+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;
-    ```
+<pre>
+```mermaid
+graph TD;
+    A-->B;
+    A-->C;
+    B-->D;
+    C-->D;
+```
+</pre>
 
 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
@@ -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
@@ -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
@@ -0,0 +1,20 @@
+# Introduction
+
+[![Go Reference](https://pkg.go.dev/badge/go.abhg.dev/goldmark/mermaid.svg)](https://pkg.go.dev/go.abhg.dev/goldmark/mermaid)
+[![CI](https://github.com/abhinav/goldmark-mermaid/actions/workflows/ci.yml/badge.svg)](https://github.com/abhinav/goldmark-mermaid/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/abhinav/goldmark-mermaid/branch/main/graph/badge.svg?token=W98KYF8SPE)](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
+<https://abhinav.github.io/goldmark-mermaid/demo/>.
+
+## Features
+
+- Client-side rendering by injecting JavaScript
+- Server-side rendering with the Mermaid CLI
diff --git a/doc/license.md 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
@@ -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
@@ -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,
+
+<pre>
+```mermaid
+graph TD;
+    A-->B;
+    A-->C;
+    B-->D;
+    C-->D;
+```
+</pre>
+
+When you render the Markdown as HTML, these will be rendered into diagrams.