An easy-to-use product documentation package in Golang.
Docweaver is suitable for product documentation and/or knowledge bases. Converts folder(s) of .md files into full-bread complete documentation. This package is without UI elements and templates, all freedom regarding final presentation is given to the end-user.
PHP/Laravel version is available here.
go get github.com/reliqarts/go-docweaver
Example .env:
DW_DOCS_DIR=./tmp/docs # Where documentation repos (archives) should be stored.
DW_ASSETS_DIR=./tmp/doc-assets # Where documentation assets should be accessed from.
DW_ROUTE_PREFIX=docs # Documentation route prefix.
DW_ASSETS_ROUTE_PREFIX=doc-assets # Route prefix for assets.
DW_SOURCES_FILE=./doc-sources.yml # Sources file location.
DW_SHOW_LOGS=true # Whether logs should be printed.
Example files:
The documentation directory is the place where you put your project documentation directories. It may be changed with
the environment variable DW_DOCS_DIR
. The default documentation directory is ./tmp/docs
.
Each project directory should contain separate folders for each documented version. Each version must have at least
two (2) markdown files, namely documentation.md
and installation.md
, which serve as the index (usually shown in sidebar) and initial
documentation pages respectively.
[doc dir]
│
└─── Project One
│ └── 1.0
│ └── 2.1
│ └── .docweaver.yml # meta file (optional)
│ └── documentation.md # sidebar nav
│ └── installation.md # initial page
│
└─── Project Two
Configurations for each doc version may be placed in .docweaver.yml
. The supported settings are:
-
Product name.
-
Product description.
-
Product image url. This may be an absolute url (e.g.
https://mywebsite.com/myimage.jpg
) or an image found in theimages
resource directory.To use the
foo.jpg
in theimages
directory you would setimage_url
to{{docs}}/images/foo.jpg
.
Gin Example
package main
import (
"github.com/gin-gonic/gin"
"github.com/reliqarts/go-docweaver"
)
func main() {
router := gin.New()
router.GET(docweaver.GetRoutePrefix(), handlers.Documentation())
router.GET(fmt.Sprintf("%s/*path", docweaver.GetRoutePrefix()), handlers.Documentation())
router.Static(docweaver.GetAssetsRoutePrefix(), docweaver.GetAssetsDir())
_ = (router).Run("localhost:8080")
}
// ...
package handlers
import (
"github.com/gin-gonic/gin"
"github.com/reliqarts/go-docweaver"
"net/http"
)
// ...
func Documentation() gin.HandlerFunc {
return func(c *gin.Context) {
path := c.Param("path")
dw := docweaver.GetRepository("")
if path == "/" || path == "" {
products, err := dw.FindAllProducts()
if err != nil {
c.HTML(code, "error.gohtml", gin.H{
"errorCode": http.StatusInternalServerError,
"errorMessage": err,
})
return
}
c.HTML(http.StatusOK, "docs/index.gohtml", gin.H{
"products": products,
})
return
}
productKey, version, pagePath := "", "", ""
pageParts := strings.Split(path, "/")
if len(pageParts) >= 2 {
productKey = pageParts[1]
}
if len(pageParts) >= 3 {
version = pageParts[2]
}
if len(pageParts) >= 4 {
pagePath = pageParts[3]
}
page, err := dw.GetPage(productKey, version, pagePath)
if err != nil {
errMsg := fmt.Sprintf("Page not found. %s", err)
c.HTML(http.StatusNotFound, "error.gohtml", gin.H{
"errorCode": http.StatusNotFound,
"errorMessage": errMsg,
})
c.Abort()
return
}
c.HTML(http.StatusOK, "documentation/show.gohtml", gin.H{
"page": page,
})
}
}
// ...
🍻 cheers