go-service-doc
This is a tool to generate a static web site based on Markdown files.
It will:
- convert Markdown files to HTML pages (more info)
- generate a menu based on
#
and ##
headers (more info)
- add styling similar to what is used by github to display Markdown files
go-service-doc also supports embedding static files, more info.
You can find a list of all features here
go-service-doc will generate both HTML files to be deployed standalone and a go
handler, which could be used in your service.
Usage
Install
go install -u github.com/SKF/go-service-doc
Run
go-service-doc
Flags
-
-s
The Index Markdown filename to use for the base path, defaults to service.md
.
-
-d
The Source Directory where the markdown files are located, defaults to docs
.
-
-o
The Output Directory where to write the generated files, defaults to docs
.
-
-p
Base path to add for the generated documentation, defaults to /docs
.
Example
You can find this example with the markdown source files and the generated output in cmd/example.
To generate the output, the following is executed from cmd/example.
go-service-doc -s bars.md -d docs/src -o docs/generated -p /go-service-doc
Example code:
package main
import (
"log"
"net/http"
service_docs "github.com/SKF/go-service-doc/cmd/example/docs/generated"
)
const port = "8080"
func main() {
server := &http.Server{Addr: ":" + port, Handler: service_docs.Handler()}
log.Printf("Will start to listen and serve on port %s", port)
if err := server.ListenAndServe(); err != http.ErrServerClosed {
log.Fatal("HTTP server ListenAndServe")
}
}
Features
HTML Page Generator
It will convert the Markdown files to HTML pages and add CSS similar to the CSS used by github to display Markdown files. The URL for the generated HTML page will be the kebab-case version of the filename excluding the extension, i.e. monkey_bar.md
will be /<base_path>/monkey-bar
.
The Side Menu is generated based on the Markdown Header Elements: #
and ##
. It will only generate entries for the headers that have a defined Header ID, like: {#header_id}
.
Search Engine
The Side Menu features a Search field that can be used to search in all generated pages. The search engine will index content based on Markdown Headers.
Embedding Images
Files found in the static
folder will be embedded in the generated go-handler and can be referenced through <base_path>/static/<file_name>
.
<src_directory>
└─ static
├─ bars.svg
├─ favicon-16x16.png
└─ favicon.ico
Supported file extensions:
How to add an image in Markdown
From cmd/example, ![The bars](/go-service-doc/static/bars.svg)
.
Favicon
If a file called favicon.ico
is found in the static
folder, it will be used as the sites favicon.
<src_directory>
└─ static
└─ favicon.ico