-
Notifications
You must be signed in to change notification settings - Fork 4
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Use stitchmd to put the README together. This will help make some of the upcoming changes easier.
- Loading branch information
Showing
8 changed files
with
169 additions
and
17 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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' |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
# goldmark-mermaid | ||
|
||
- [Introduction](intro.md) | ||
- [Installation](install.md) | ||
- [Usage](usage.md) | ||
- [Rendering methods](render.md) | ||
- [License](license.md) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
# Installation | ||
|
||
Install the latest version of the library with Go modules. | ||
|
||
```bash | ||
go get go.abhg.dev/goldmark/mermaid@latest | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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) | ||
[![Go](https://github.com/abhinav/goldmark-mermaid/actions/workflows/go.yml/badge.svg)](https://github.com/abhinav/goldmark-mermaid/actions/workflows/go.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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
# License | ||
|
||
This software is made available under the MIT license. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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`. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |