KnowledgeBase
knowledgebase is a tool to quickly generate a knowledge base server.
Showcase
Usage
There are two ways to use it.
- As a CLI tool. Run the command, visit your site. MORE
- As a library. Add a docs server to your Go server. MORE
The directory with your documentation needs two sub-directories.
-
A directory containing your markdown files. Default pages.
In this directory, there should be a file named index.md
which will be the file rendered at the root of your server.
Every other page or folder must begin with a number, e.g. 01 Get Started
. This is used to order them in the sidebar menu.
-
A directory containing static assets. Default assets.
In your markdown pages, you can refer to any of these as /assets/my-static-file.jpg
.
The CLI tool allows you to start a web server leading to your documentation.
To install the command line tool, you should have Go
installed.
go get github.com/stephenafamo/knowledgebase/cmd/knowledgebase
# Check the help menu
knowledgebase -h
The help menu:
Start a knowledgebase server
Usage:
knowledgebase [flags]
Flags:
-a, --assets string Path to the assets directory (default "assets")
-d, --docs string Path to the markdown pages (default "docs")
-h, --help help for knowledgebase
-p, --port int Port to start the server on (default 80)
Use as a Library
You can use this as a library, it will return a http.Handler
which you can mount on any router. There are some more options when using it this way.
type Config struct {
Docs fs.FS // Store containing the docs
Assets fs.FS // Store containing the assets
// mount path for links in the menu. Default "/"
// Useful if the handler is to be mounted in a subdirectory of the server
MountPath string
// RootURL is the main application URL. Useful if the knowledgebase is part of a larger application
// Default is the MountPath
RootURL string
// RootLabel is the label for the "Home" link at the top of the sidebar. Default: Home
RootLabel string
// MountLabel is the label for the documentation root.
// It will not be displayed in the sidebar if empty OR if the
// RootURL is not set or the RootURL is the same as the MountPath.
// In these scenarios, the RootURL is the MountPath and the RootLabel will suffice
MountLabel string
// BaseMenu is a list of menu items that will be displayed before the
// menu generated from the pages.
// Example:
// BaseMenu: []*knowledgebase.MenuItem{
// {
// Label: "Back to main site",
// Path: "/",
// },
// {
// Label: "Login",
// Path: "http://example.com/login",
// },
// {
// Label: "Signup",
// Path: "http://example.com/signup",
// },
// },
BaseMenu []*MenuItem
Searcher search.Searcher
// Used to style some elements in the documentation, such as links
PrimaryColor string
// An optional logo that will be displayed on the sidebar
// A link to the image is needed. Should be square. Will be used as the src
// A data URI can be used
Logo template.URL
InHead, BeforeBody, AfterBody template.HTML
// This content will be added at the end of every doc page
// BEFORE the markdown is converted to HTML
// A good use for this is to add markdown link references that are used in
// multiple places. see https://spec.commonmark.org/0.29/#link-reference-definition
SharedMarkdown string
}
type MenuItem struct {
Label string
Path string
Children []*MenuItem
}
You create a new knowledgebase
instance by calling the New()
method:
ctx := context.Background()
config := knowledgebase.Config{
// Setup configuration
}
kb, err := knowledgebase.New(ctx, config)
if err != nil {
// handle error
}
handler := kb.Handler()
Examples
Using as a standalone webserver
package main
import (
"context"
"net/http"
"os"
"github.com/stephenafamo/knowledgebase"
)
func main() {
ctx := context.Background()
config := knowledgebase.Config{
Docs: os.DirFS("./docs"),
}
kb, err := knowledgebase.New(ctx, config)
if err != nil {
panic(err)
}
http.ListenAndServe(":8080", kb)
}
Mount in subdirectory with Gorrila Mux
package main
import (
"context"
"net/http"
"os"
"github.com/gorilla/mux"
"github.com/stephenafamo/knowledgebase"
)
func main() {
ctx := context.Background()
config := knowledgebase.Config{
Docs: os.DirFS("./docs"),
MountPath: "/docs",
}
kb, err := knowledgebase.New(ctx, config)
if err != nil {
panic(err)
}
r := mux.NewRouter()
r.PathPrefix("/docs/").Handler(http.StripPrefix("/docs/", kb))
http.ListenAndServe(":8080", r)
}
Mount in subdirectory with Chi
package main
import (
"context"
"net/http"
"os"
"github.com/go-chi/chi/v5"
"github.com/stephenafamo/knowledgebase"
)
func main() {
ctx := context.Background()
config := knowledgebase.Config{
Docs: os.DirFS("./docs"),
MountPath: "/docs",
}
kb, err := knowledgebase.New(ctx, config)
if err != nil {
panic(err)
}
r := chi.NewRouter()
r.Mount("/docs", http.StripPrefix("/docs", kb))
http.ListenAndServe(":8080", r)
}
Contributing
Looking forward to pull requests.