Markdown Template
Godocdown can render the output into markdown template. This way, you can generate markdown files as an output.
NOTE: This is an extension from the General Template. Please read that document before continuing.
Command Parameters
One very important step to enable the use of Markdown template is to:
- include the filename with
.md
extension (strict rule)
Example:
$ godocgen --filename _index.md ...
Designing Template
Godocgen uses component-driven to render the template like the other formats do.
For Markdown, it uses Go's text/template
standard package for rendering.
Head
For Markdown Head
component, if you're using technologies that requiring
head section (e.g. Hugo Markdown), you can use this section to render your
Markdown.
General Use
For general use, we suggest you can do something as such:
[comment]: # (WARNING: This markdown is autogenerated by bot.)
[comment]: # ( Do not edit it manually!)
This will warn any other developers that the markdown documentations are generated automatically using godocgen.
Hugo
For Hugo front-matter, we suggest you can do something as such:
{{- define "Head" -}}
<!--
# WARNING: This markdown is autogenerated by bot. Do not edit it manually!
date = "{{- .HugoTimestamp -}}"
title = "{{- .Header -}}"
description = """
{{ .Synopsis }}
"""
keywords = [ "{{- .Header -}}", "go" ]
authors = [ "Godocgen Team" ]
draft = false
type = ""
layout = "single"
# thumbnailURL = "#"
[menu.main]
parent = "X) Go Doc"
name = "{{- if .Name -}}{{- .Name -}}{{- else -}}{{- .Header -}}{{- end -}}"
weight = 1
-->
{{ end -}}
Title
For Markdown Title
component, you can do something as such:
{{- define "Title" -}}
# {{ .Header }} {{ .Name }}
{{ end -}}
ImportPath
For Markdown ImportPath
component, you can do something as such:
{{- define "ImportPath" -}}
```go
import "{{- .Value -}}"
```
{{ end -}}
Header
For Markdown Header
component, you can do something as such:
{{- define "Header" }}
## {{ .Name }}
{{ end -}}
Synopsis
For Markdown Synopsis
component, you can do something as such:
{{- define "Synopsis" -}}
{{ .Synopsis }}
{{- end }}
DeclGroup
For Markdown DeclGroup
component, you can do something as such:
{{- define "DeclGroup" -}}
```go
{{ .Name }} (
{{- end }}
DeclElements
For Markdown DeclElements
component, you can do something as such:
{{- define "DeclElements" -}}
{{- if .Header }}
{{ .Header }}
{{- end }}
{{ .Value }}
{{ end -}}
EndDeclGroup
For Markdown EndDeclGroup
component, you can do something as such:
{{- define "EndDeclGroup" -}}
)
```
{{ end -}}
Function
For Markdown Function
component, you can do something as such:
{{- define "Function" -}}
### `Func {{ .Value }}`
{{ .Header }}
{{ end -}}
Code
For Markdown Code
component, you can do something as such:
{{- define "Code" -}}
```go
{{- range $i, $line := .Codes }}
{{ $line }}
{{- end }}
```
{{ end -}}
NewLine
For Markdown NewLine
component, you can do something as such:
{{- define "NewLine" }}
{{ end -}}
Example
For Markdown Example
component, you can do something as such:
NOTE: ONLY available starting from
v0.0.2
onwards.
{{- define "Example" -}}
{{- if and .Header .Name -}}
{{ .Header }} {{ .Name }} Example:
{{ else if and .Header (not .Name) -}}
{{ .Header }} Example:
{{ else if and (not .Header) .Name -}}
First Example:
{{ end -}}
{{- if .Synopsis -}}
{{ .Synopsis }}
{{ end -}}
```go
{{- range $i, $line := .Codes }}
{{ $line }}
{{- end }}
{{- if .Value }}
// Output:
// {{ .Value }}
{{- end -}}
```
{{ end -}}