{"id":16445561,"url":"https://github.com/stephenafamo/knowledgebase","last_synced_at":"2025-10-27T05:31:48.148Z","repository":{"id":57544375,"uuid":"296738698","full_name":"stephenafamo/knowledgebase","owner":"stephenafamo","description":"knowldegebase is a tool to quickly start a knowledge base server or add one to a go web app.","archived":false,"fork":false,"pushed_at":"2023-08-06T16:49:11.000Z","size":729,"stargazers_count":5,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-01T03:08:15.081Z","etag":null,"topics":["go","golang","knowledge-base","knowledgebase"],"latest_commit_sha":null,"homepage":"https://stephenafamo.com","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stephenafamo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-09-18T22:05:15.000Z","updated_at":"2023-08-17T08:58:54.000Z","dependencies_parsed_at":"2022-09-16T23:12:03.836Z","dependency_job_id":null,"html_url":"https://github.com/stephenafamo/knowledgebase","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stephenafamo%2Fknowledgebase","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stephenafamo%2Fknowledgebase/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stephenafamo%2Fknowledgebase/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stephenafamo%2Fknowledgebase/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stephenafamo","download_url":"https://codeload.github.com/stephenafamo/knowledgebase/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238445854,"owners_count":19473823,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go","golang","knowledge-base","knowledgebase"],"created_at":"2024-10-11T09:44:46.221Z","updated_at":"2025-10-27T05:31:42.312Z","avatar_url":"https://github.com/stephenafamo.png","language":"Go","readme":"# KnowledgeBase\n\nknowledgebase is a tool to quickly generate a knowledge base server.\n\n### Showcase\n\n* [Swish.ink help docs](https://swish.ink/docs)\n\n## Usage\n\nThere are two ways to use it.\n\n* As a CLI tool. Run the command, visit your site. [MORE](#use-as-a-cli-tool)\n* As a library. Add a docs server to your Go server. [MORE](#use-as-a-library)\n\nThe directory with your documentation needs two sub-directories.\n\n1. A directory containing your markdown files. Default **pages**.\n\n    In this directory, there should be a file named `index.md` which will be the file rendered at the root of your server.\n\n    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.\n\n2. A directory containing static assets. Default **assets**.\n\n    In your markdown pages, you can refer to any of these as `/assets/my-static-file.jpg`.\n\n### Use as a CLI tool\n\nThe CLI tool allows you to start a web server leading to your documentation.\n\nTo install the command line tool, you should have `Go` installed.\n\n```sh\ngo get github.com/stephenafamo/knowledgebase/cmd/knowledgebase\n\n# Check the help menu\nknowledgebase -h\n```\n\nThe help menu: \n\n```\nStart a knowledgebase server\n\nUsage:\n  knowledgebase [flags]\n\nFlags:\n  -a, --assets string   Path to the assets directory (default \"assets\")\n  -d, --docs string     Path to the markdown pages (default \"docs\")\n  -h, --help            help for knowledgebase\n  -p, --port int        Port to start the server on (default 80)\n```\n\n### Use as a Library\n\nYou can use this as a library, it will return a [`http.Handler`](https://golang.org/pkg/net/http/#Handler) which you can mount on any router. There are some more options when using it this way.\n\n```go\ntype Config struct {\n\tDocs   fs.FS // Store containing the docs\n\tAssets fs.FS // Store containing the assets\n\n\t// mount path for links in the menu. Default \"/\"\n\t// Useful if the handler is to be mounted in a subdirectory of the server\n\tMountPath string\n\n\t// RootURL is the main application URL. Useful if the knowledgebase is part of a larger application\n\t// Default is the MountPath\n\tRootURL string\n\n\t// RootLabel is the label for the \"Home\" link at the top of the sidebar. Default: Home\n\tRootLabel string\n\n\t// MountLabel is the label for the documentation root.\n\t// It will not be displayed in the sidebar if empty OR if the\n\t// RootURL is not set or the RootURL is the same as the MountPath.\n\t// In these scenarios, the RootURL is the MountPath and the RootLabel will suffice\n\tMountLabel string\n\n\t// BaseMenu is a list of menu items that will be displayed before the\n\t// menu generated from the pages.\n\t// Example:\n\t// BaseMenu: []*knowledgebase.MenuItem{\n\t//     {\n\t//         Label: \"Back to main site\",\n\t//         Path:  \"/\",\n\t//     },\n\t//     {\n\t//         Label: \"Login\",\n\t//         Path:  \"http://example.com/login\",\n\t//     },\n\t//     {\n\t//         Label: \"Signup\",\n\t//         Path:  \"http://example.com/signup\",\n\t//     },\n\t// },\n\tBaseMenu []*MenuItem\n\n\tSearcher search.Searcher\n\n\t// Used to style some elements in the documentation, such as links\n\tPrimaryColor string\n\n\t// An optional logo that will be displayed on the sidebar\n\t// A link to the image is needed. Should be square. Will be used as the src\n\t// A data URI can be used\n\tLogo template.URL\n\n\tInHead, BeforeBody, AfterBody template.HTML\n\n\t// This content will be added at the end of every doc page\n\t// BEFORE the markdown is converted to HTML\n\t// A good use for this is to add markdown link references that are used in\n\t// multiple places. see https://spec.commonmark.org/0.29/#link-reference-definition\n\tSharedMarkdown string\n}\n\ntype MenuItem struct {\n\tLabel    string\n\tPath     string\n\tChildren []*MenuItem\n}\n```\n\nYou create a new `knowledgebase` instance by calling the `New()` method:\n\n```go\nctx := context.Background()\nconfig := knowledgebase.Config{\n    // Setup configuration\n}\n\nkb, err := knowledgebase.New(ctx, config)\nif err != nil {\n    // handle error\n}\n\nhandler := kb.Handler()\n```\n\n#### Examples\n\nUsing as a standalone webserver\n\n```go\npackage main\n\nimport (\n\t\"context\"\n\t\"net/http\"\n\t\"os\"\n\n\t\"github.com/stephenafamo/knowledgebase\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tconfig := knowledgebase.Config{\n\t\tDocs: os.DirFS(\"./docs\"),\n\t}\n\n\tkb, err := knowledgebase.New(ctx, config)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\thttp.ListenAndServe(\":8080\", kb)\n}\n```\n\nMount in subdirectory with Gorrila Mux\n\n```go\npackage main\n\nimport (\n\t\"context\"\n\t\"net/http\"\n\t\"os\"\n\n\t\"github.com/gorilla/mux\"\n\t\"github.com/stephenafamo/knowledgebase\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tconfig := knowledgebase.Config{\n        Docs:     os.DirFS(\"./docs\"),\n\t\tMountPath: \"/docs\",\n\t}\n\n\tkb, err := knowledgebase.New(ctx, config)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\tr := mux.NewRouter()\n\tr.PathPrefix(\"/docs/\").Handler(http.StripPrefix(\"/docs/\", kb))\n\n\thttp.ListenAndServe(\":8080\", r)\n}\n```\n\nMount in subdirectory with Chi\n\n```go\npackage main\n\nimport (\n\t\"context\"\n\t\"net/http\"\n\t\"os\"\n\n\t\"github.com/go-chi/chi/v5\"\n\t\"github.com/stephenafamo/knowledgebase\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tconfig := knowledgebase.Config{\n\t\tDocs:     os.DirFS(\"./docs\"),\n\t\tMountPath: \"/docs\",\n\t}\n\n\tkb, err := knowledgebase.New(ctx, config)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\tr := chi.NewRouter()\n\tr.Mount(\"/docs\", http.StripPrefix(\"/docs\", kb))\n\n\thttp.ListenAndServe(\":8080\", r)\n}\n```\n\n## Contributing\n\nLooking forward to pull requests.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstephenafamo%2Fknowledgebase","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstephenafamo%2Fknowledgebase","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstephenafamo%2Fknowledgebase/lists"}