markdown
Markdown builder that generates GitHub Flavored Markdown and mermaid diagrams through method chaining
About markdown
This large README is shown as a plain-text preview. Read the full README at the source
<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
[](#contributors-)
<!-- ALL-CONTRIBUTORS-BADGE:END -->
[](https://github.com/avelino/awesome-go)
[](https://pkg.go.dev/github.com/nao1215/markdown)
[](https://github.com/nao1215/markdown/actions/workflows/unit_test.yml)
[](https://github.com/nao1215/markdown/actions/workflows/reviewdog.yml)
[](https://github.com/nao1215/markdown/actions/workflows/gosec.yml)
[](https://scorecard.dev/viewer/?uri=github.com/nao1215/markdown)
# What is markdown package
The markdown package is a simple Markdown builder in Go. It assembles Markdown using method chaining, and does not use a template engine like [html/template](https://pkg.go.dev/html/template). The syntax follows GitHub Markdown.
It covers the GitHub Markdown syntax: headings, lists, checkbox lists, tables, code blocks, blockquotes, horizontal rules, text formatting, links, images, details, footnotes, math expressions, and alerts. It also builds 24 mermaid diagram types, from sequence and flowchart to Gantt, C4 context, and Wardley map; each one has an example below. Two helpers go beyond Markdown syntax: status badges and an index for a directory full of markdown files.
Complex code that increases the complexity of the library, such as generating nested lists, will not be added. I want to keep this library as simple as possible.
## Supported OS and go version
- OS: Linux, macOS, Windows
- Go: 1.26 or later
## Example
### Basic usage
```go
package main
import (
"os"
md "github.com/nao1215/markdown"
)
func main() {
md.NewMarkdown(os.Stdout, md.WithBlockSpacing()).
H1("This is H1").
PlainText("This is plain text").
H2f("This is %s with text format", "H2").
PlainTextf("Text formatting, such as %s and %s, %s styles.",
md.Bold("bold"), md.Italic("italic"), md.Code("code")).
H2("Code Block").
CodeBlocks(md.SyntaxHighlightGo,
`package main
import "fmt"
func main() {
fmt.Println("Hello, World!")
}`).
H2("List").
BulletList("Bullet Item 1", "Bullet Item 2", "Bullet Item 3").
OrderedList("Ordered Item 1", "Ordered Item 2", "Ordered Item 3").
H2("CheckBox").
CheckBox([]md.CheckBoxSet{
{Checked: false, Text: md.Code("sample code")},
{Checked: true, Text: md.Link("Go", "https://golang.org")},
{Checked: false, Text: md.Strikethrough("strikethrough")},
}).
H2("Blockquote").
Blockquote("If you can dream it, you can do it.").
H3("Horizontal Rule").
HorizontalRule().
H2("Table").
Table(md.TableSet{
Header: []string{"Name", "Age", "Country"},
Rows: [][]string{
{"David", "23", "USA"},
{"John", "30", "UK"},
{"Bob", "25", "Canada"},
},
}).
H2("Image").
PlainTextf(md.Image("sample_image", "./sample.png")).
Build()
}
```
Output:
````
# This is H1
This is plain text
## This is H2 with text format
Text formatting, such as **bold** and *italic*, `code` styles.
## Code Block
```go
package main
import "fmt"
func main() {
fmt.Println("Hello, World!")
}
```
## List
- Bullet Item 1
- Bullet Item 2
- Bullet Item 3
1. Ordered Item 1
2. Ordered Item 2
3. Ordered Item 3
## CheckBox
- [ ] `sample code`
- [x] [Go](https://golang.org)
- [ ] ~~strikethrough~~
## Blockquote
> If you can dream it, you can do it.
### Horizontal Rule
---
## Table
| Name | Age | Country |
|---------|---------|---------|
| David | 23 | USA |
| John | 30 | UK |
| Bob | 25 | Canada |
## Image
````
If you want to see how it looks in Markdown, please refer to the following link.
- [sample.md](./doc/generated_example.md)
### Generate Markdown using `"go generate ./..."`
You can generate Markdown using `go generate`. Please define code to generate Markdown first. Then, run `"go generate ./..."` to generate Markdown.
[Code example:](./doc/generate/main.go)
```go
package main
import (
"os"
md "github.com/nao1215/markdown"
)
//go:generate go run main.go
func main() {
f, err := os.Create("generated.md")
if err != nil {
panic(err)
}
defer f.Close()
md.NewMarkdown(f).
H1("go generate example").
PlainText("This markdown is generated by `go generate`").
Build()
}
```
Run below command:
```shell
go generate ./...
```
[Output:](./doc/generate/generated.md)
````text
# go generate example
This markdown is generated by `go generate`
````
### Alerts syntax
The markdown package can create alerts. Alerts are useful for displaying important information in Markdown. This syntax is supported by GitHub.
[Code example:](./doc/alert/main.go)
```go
md.NewMarkdown(f).
H1("Alert example").
Note("This is note").LF().
Tip("This is tip").LF().
Important("This is important").LF().
Warning("This is warning").LF().
Caution("This is caution").LF().
Build()
```
[Output:](./doc/alert/generated.md)
````text
# Alert example
> [!NOTE]
> This is note
> [!TIP]
> This is tip
> [!IMPORTANT]
> This is important
> [!WARNING]
> This is warning
> [!CAUTION]
> This is caution
````
Your alert will look like this;
> [!NOTE]
> This is note
> [!TIP]
> This is tip
> [!IMPORTANT]
> This is important
> [!WARNING]
> This is warning
> [!CAUTION]
> This is caution
### Status badge syntax
The markdown package can create red, yellow, and green status badges.
[Code example:](./doc/badge/main.go)
```go
md.NewMarkdown(os.Stdout).
H1("badge example").
RedBadge("red_badge").
YellowBadge("yellow_badge").
GreenBadge("green_badge").
BlueBadge("blue_badge").
Build()
```
[Output:](./doc/badge/generated.md)
````text
# badge example
````
Your badge will look like this;
### Mermaid sequence diagram syntax
```go
package main
import (
"io"
"os"
"github.com/nao1215/markdown"
"github.com/nao1215/markdown/mermaid/sequence"
)
//go:generate go run main.go
func main() {
diagram := sequence.NewDiagram(io.Discard).
Participant("Sophia").
Participant("David").
Participant("Subaru").
LF().
SyncRequest("Sophia", "David", "Please wake up Subaru").
SyncResponse("David", "Sophia", "OK").
LF().
LoopStart("until Subaru wake up").
SyncRequest("David", "Subaru", "Wake up!").
SyncResponse("Subaru", "David", "zzz").
SyncRequest("David", "Subaru", "Hey!!!").
BreakStart("if Subaru wake up").
SyncResponse("Subaru", "David", "......").
BreakEnd().
LoopEnd().
LF().
SyncResponse("David", "Sophia", "wake up, wake up").
String()
markdown.NewMarkdown(os.Stdout, markdown.WithBlockSpacing()).
H2("Sequence Diagram").
CodeBlocks(markdown.SyntaxHighlightMermaid, diagram).
Build()
}
```
Plain text output: [markdown is here](./doc/sequence/generated.md)
````
## Sequence Diagram
```mermaid
sequenceDiagram
participant Sophia
participant David
participant Subaru
Sophia->>David: Please wake up Subaru
David-->>Sophia: OK
loop until Subaru wake up
David->>Subaru: Wake up!
Subaru-->>David: zzz
David->>Subaru: Hey!!!
break if Subaru wake up
Subaru-->>David: ......
end
end
David-->>Sophia: wake up, wake up
```
````
Mermaid output:
```mermaid
sequenceDiagram
participant Sophia
participant David
participant Subaru
Sophia->>David: Please wake up Subaru
David-->>Sophia: OK
loop until Subaru wake up
David->>Subaru: Wake up!
Subaru-->>David: zzz
David->>Subaru: Hey!!!
break if Subaru wake up
Subaru-->>David: ......
end
end
David-->>Sophia: wake up, wake up
```
### Mermaid user journey diagram syntax
```go
package main
import (
"io"
"os"
"github.com/nao1215/markdown"
"github.com/nao1215/markdown/mermaid/userjourney"
)
//go:generate go run main.go
func main() {
diagram := userjourney.NewDiagram(
io.Discard,
userjourney.WithTitle("Checkout Journey"),
).
Section("Discover").
Task("Browse products", userjourney.ScoreVerySatisfied, "Customer").
Task("Add item to cart", userjourney.ScoreSatisfied, "Customer").
LF().
Section("Checkout").
Task("Enter shipping details", userjourney.ScoreNeutral, "Customer").
Task("Complete payment", userjourney.ScoreSatisfied, "Customer", "Payment Service").
String()
if err := markdown.NewMarkdown(os.Stdout, markdown.WithBlockSpacing()).
H2("User Journey Diagram").
CodeBlocks(markdown.SyntaxHighlightMermaid, diagram).
Build(); err != nil {
panic(err)
}
}
```
Plain text output: [markdown is here](./doc/userjourney/generated.md)
````text
## User Journey Diagram
```mermaid
journey
title Checkout Journey
section Discover
Browse products: 5: Customer
Add item to cart: 4: Customer
section Checkout
Enter shipping details: 3: Customer
Complete payment: 4: Customer, Payment Service
```
````
Mermaid output:
```mermaid
journey
title Checkout Journey
section Discover
Browse products: 5: Customer
Add item to cart: 4: Customer
section Checkout
Enter shipping details: 3: Customer
Complete payment: 4: Customer, Payment Service
```
### Mermaid git graph syntax
```go
package main
import (
"io"
"os"
"github.com/nao1215/markdown"
"github.com/nao1215/markdown/mermaid/gitgraph"
)
//go:generate go run main.go
func main() {
diagram := gitgraph.NewDiagram(
io.Discard,
gitgraph.WithTitle("Release Flow"),
).
Commit(gitgraph.WithCommitID("init"), gitgraph.WithCommitTag("v0.1.0")).
Branch("develop", gitgraph.WithBranchOrder(2)).
Checkout("develop").
Commit(gitgraph.WithCommitType(gitgraph.CommitTypeHighlight)).
Checkout("main").
Merge("develop", gitgraph.WithCommitTag("v1.0.0")).
String()
if err := markdown.NewMarkdown(os.Stdout, markdown.WithBlockSpacing()).
H2("Git Graph").
CodeBlocks(markdown.SyntaxHighlightMermaid, diagram).
Build(); err != nil {
panic(err)
}
}
```
Plain text output: [markdown is here](./doc/gitgraph/generated.md)
````text
## Git Graph
```mermaid
---
title: "Release Flow"
---
gitGraph
commit id: "init" tag: "v0.1.0"
branch develop order: 2
checkout develop
commit type: HIGHLIGHT
checkout main
merge develop tag: "v1.0.0"
```
````
Mermaid output:
```mermaid
---
title: "Release Flow"
---
gitGraph
commit id: "init" tag: "v0.1.0"
branch develop order: 2
checkout develop
commit type: HIGHLIGHT
checkout main
merge develop tag: "v1.0.0"
```
### Mermaid mindmap syntax
```go
package main
import (
"io"
"os"
"github.com/nao1215/markdown"
"github.com/nao1215/markdown/mermaid/mindmap"
)
//go:generate go run main.go
func main() {
diagram := mindmap.NewDiagram(
io.Discard,
mindmap.WithTitle("Product Strategy Mindmap"),
).
Root("Product Strategy").
Child("Market").
Child("SMB").
Sibling("Enterprise").
Parent().
Sibling("Execution").
Child("Q1").
Sibling("Q2").
String()
if err := markdown.NewMarkdown(os.Stdout, markdown.WithBlockSpacing()).
H2("Mindmap").
CodeBlocks(markdown.SyntaxHighlightMermaid, diagram).
Build(); err != nil {
panic(err)
}
}
```
Plain text output: [markdown is here](./doc/mindmap/generated.md)
````text
## Mindmap
```mermaid
---
title: "Product Strategy Mindmap"
---
mindmap
Product Strategy
Market
SMB
Enterprise
Execution
Q1
Q2
```
````
Mermaid output:
```mermaid
---
title: "Product Strategy Mindmap"
---
mindmap
Product Strategy
Market
SMB
Enterprise
Execution
Q1
Q2
```
### Mermaid requirement diagram syntax
```go
package main
import (
"io"
"os"
"github.com/nao1215/markdown"
"github.com/nao1215/markdown/mermaid/requirement"
)
//go:generate go run main.go
func main() {
diagram := requirement.NewDiagram(
io.Discard,
requirement.WithTitle("Checkout Requirements"),
).
SetDirection(requirement.DirectionTB).
Requirement(
"Login",
requirement.WithID("REQ-1"),
requirement.WithText("The system shall support login."),
requirement.WithRisk(requirement.RiskHigh),
requirement.WithVerifyMethod(requirement.VerifyMethodTest),
requirement.WithRequirementClasses("critical"),
).
FunctionalRequirement(
"RememberSession",
requirement.WithID("REQ-2"),
requirement.WithText("The system shall remember the user."),
requirement.WithRisk(requirement.RiskMedium),
requirement.WithVerifyMethod(requirement.VerifyMethodInspection),
).
Element(
"AuthService",
requirement.WithElementType("system"),
requirement.WithDocRef("docs/auth.md"),
requirement.WithElementClasses("service"),
).
From("AuthService").
Satisfies("Login").
From("RememberSession").
Verifies("Login").
ClassDefs(
requirement.Def("critical", "fill:#f96,stroke:#333,stroke-width:2px"),
requirement.Def("service", "fill:#9cf,stroke:#333,stroke-width:1px"),
).
String()
if err := markdown.NewMarkdown(os.Stdout, markdown.WithBlockSpacing()).
H2("Requirement Diagram").
CodeBlocks(markdown.SyntaxHighlightMermaid, diagram).
Build(); err != nil {
panic(err)
}
}
```
Plain text output: [markdown is here](./doc/requirement/generated.md)
````text
## Requirement Diagram
```mermaid
---
title: "Checkout Requirements"
---
requirementDiagram
direction TB
requirement Login:::critical {
id: "REQ-1"
text: "The system shall support login."
risk: High
verifymethod: Test
}
functionalRequirement RememberSession {
id: "REQ-2"
text: "The system shall remember the user."
risk: Medium
verifymethod: Inspection
}
element AuthService:::service {
type: "system"
docRef: "docs/auth.md"
}
AuthService - satisfies -> Login
RememberSession - verifies -> Login
classDef critical fill:#f96,stroke:#333,stroke-width:2px
classDef service fill:#9cf,stroke:#333,stroke-width:1px
```
````
Mermaid output:
```mermaid
---
title: "Checkout Requirements"
---
requirementDiagram
direction TB
requirement Login:::critical {
id: "REQ-1"
text: "The system shall support login."
risk: High
verifymethod: Test
}
functionalRequirement RememberSession {
id: "REQ-2"
text: "The system shall remember the user."
risk: Medium
verifymethod: Inspection
}
element AuthService:::service {
type: "system"
docRef: "docs/auth.md"
}
AuthService - satisfies -> Login
RememberSession - verifies -> Login
classDef critical fill:#f96,stroke:#333,stroke-width:2px
classDef service fill:#9cf,stroke:#333,stroke-width:1px
```
### Mermaid XY chart syntax
```go
package main
import (
"io"
"os"
"github.com/nao1215/markdown"
"github.com/nao1215/markdown/mermaid/xychart"
)
//go:generate go run main.go
func main() {
diagram := xychart.NewDiagram(
io.Discard,
xychart.WithTitle("Sales Revenue"),
).
XAxisLabels("Jan", "Feb", "Mar", "Apr", "May", "Jun").
YAxisRangeWithTitle("Revenue (k$)", 0, 100).
Bar(25, 40, 60, 80, 70, 90).
Line(30, 50, 70, 85, 75, 95).
String()
if err := markdown.NewMarkdown(os.Stdout, markdown.WithBlockSpacing()).
H2("XY Chart").
CodeBlocks(markdown.SyntaxHighlightMermaid, diagram).
Build(); err != nil {
panic(err)
}
}
```
Plain text output: [markdown is here](./doc/xychart/generated.md)
````text
## XY Chart
```mermaid
xychart
title "Sales Revenue"
x-axis [Jan, Feb, Mar, Apr, May, Jun]
y-axis "Revenue (k$)" 0 --> 100
bar [25, 40, 60, 80, 70, 90]
line [30, 50, 70, 85, 75, 95]
```
````
Mermaid output:
```mermaid
xychart
title "Sales Revenue"
x-axis [Jan, Feb, Mar, Apr, May, Jun]
y-axis "Revenue (k$)" 0 --> 100
bar [25, 40, 60, 80, 70, 90]
line [30, 50, 70, 85, 75, 95]
```
### Mermaid packet syntax
```go
package main
import (
"io"
"os"
"github.com/nao1215/markdown"
"github.com/nao1215/markdown/mermaid/packet"
)
//go:generate go run main.go
func main() {
diagram := packet.NewDiagram(
io.Discard,
packet.WithTitle("UDP Packet"),
).
Next(16, "Source Port").
Next(16, "Destination Port").
Field(32, 47, "Length").
Field(48, 63, "Checksum").
Field(64, 95, "Data (variable length)").
String()
if err := markdown.NewMarkdown(os.Stdout, markdown.WithBlockSpacing()).
H2("Packet").
CodeBlocks(markdown.SyntaxHighlightMermaid, diagram).
Build(); err != nil {
panic(err)
}
}
```
Plain text output: [markdown is here](./doc/packet/generated.md)
````text
## Packet
```mermaid
packet
title UDP Packet
+16: "Source Port"
+16: "Destination Port"
32-47: "Length"
48-63: "Checksum"
64-95: "Data (variable length)"
```
````
Mermaid output:
```mermaid
packet
title UDP Packet
+16: "Source Port"
+16: "Destination Port"
32-47: "Length"
48-63: "Checksum"
64-95: "Data (variable length)"
```
### Mermaid block syntax
```go
package main
import (
"io"
"os"
"github.com/nao1215/markdown"
"github.com/nao1215/markdown/mermaid/block"
)
//go:generate go run main.go
func main() {
diagram := block.NewDiagram(
io.Discard,
block.WithTitle("Checkout Architecture"),
).
Columns(3).
Row(
block.Node("Frontend"),
block.ArrowRight("toBackend", block.WithArrowLabel("calls")),
block.Node("Backend"),
).
Row(
block.Space(2),
block.ArrowDown("toDB"),
).
Row(
block.Node("Database", block.WithNodeLabel("Primary DB"), block.WithNodeShape(block.ShapeCylinder)),
block.Space(),
block.Node("Cache", block.WithNodeLabel("Cache"), block.WithNodeShape(block.ShapeRound)),
).
Link("Backend", "Database").
LinkWithLabel("Backend", "reads from", "Cache").
String()
if err := markdown.NewMarkdown(os.Stdout, markdown.WithBlockSpacing()).
H2("Block Diagram").
CodeBlocks(markdown.SyntaxHighlightMermaid, diagram).
Build(); err != nil {
panic(err)
}
}
```
Plain text output: [markdown is here](./doc/block/generated.md)
````text
## Block Diagram
```mermaid
---
title: "Checkout Architecture"
---
block
columns 3
Frontend toBackend<["calls"]>(right) Backend
space:2 toDB<[" "]>(down)
Database[("Primary DB")] space Cache("Cache")
Backend --> Database
Backend -- "reads from" --> Cache
```
````
Mermaid output:
```mermaid
---
title: "Checkout Architecture"
---
block
columns 3
Frontend toBackend<["calls"]>(right) Backend
space:2 toDB<[" "]>(down)
Database[("Primary DB")] space Cache("Cache")
Backend --> Database
Backend -- "reads from" --> Cache
```
### Mermaid kanban syntax
```go
package main
import (
"io"
"os"
"github.com/nao1215/markdown"
"github.com/nao1215/markdown/mermaid/kanban"
)
//go:generate go run main.go
func main() {
diagram := kanban.NewDiagram(
io.Discard,
kanban.WithTitle("Sprint Board"),
kanban.WithTicketBaseURL("https://example.com/tickets/"),
).
Column("Todo").Frequently Asked Questions
What is markdown?
markdown is a Text Processing library for the Go programming language. Markdown builder that generates GitHub Flavored Markdown and mermaid diagrams through method chaining
How do I install markdown?
Install markdown with the Go module system using `go get nao1215/markdown`. Check the repository for the current installation instructions.
What category does markdown belong to?
markdown is listed under Text Processing, specifically Markup Languages.