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:

1. 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 -}}