Demo: docsascode.codeandmedia.com
I was inspired by Linode's approach to creating and managing docs. They call it docs as code methodology. Thereby my aim was making simple and productive way to work with any sort of documents and articles through Markdown, Git and Docker/k8s optionally.
The repo contains a theme for Zola (the best static site generator I've ever seen) and dockerfile for building Docker images with Nginx-alpine. You can pull to your Docker an image with demo-content
codeandmedia/docsascode-theme:latest
If you would use Docker on MacBook M1 processors \ Raspberry Pi4 64bit \ Amazon Graviton or another ARM64 - just fork the ARM64 branch or push
codeandmedia/docsascode-theme-arm64:latest
Perks
- light / dark switcher
- tags and authors taxonomies by default
- search
- useful UI both on mobiles and desktops
6 steps build your knowledge base/docs repo
- Fork the repo
- delete demo content and add your own (I explain how to structure it below)
- change website name and domain in config.toml, also, change the title in _index.md in a root
- connect your repo to dockerhub
- build your docker image or setup autobuilds
- host a builded docker image on your own way
But, zola is amazing static site generator, so you feel free to
- download all repo files
- again delete demo content and add your own
- change name and domain in config.toml/index.md
- setup zola (win, linux, mac)
- execute zola build
- host builded html-output anywhere you want
Zola supports Netlify and other similar services, or you can decide to create your own CI/CD process.
How to structure your content
All your articles should be inside content folder. Any images, videos, other static files should be inside static.
Folders
Every folder should contains _index.md like
+++
title = "Docsascode title"
description = "Description is optional"
sort_by = "date" # sort by weight or date
insert_anchor_links = "right" # if you want § next to headers
+++
Each folder is the section of the website, it means if you create folder foo it will be seen as yoursitedomain.com/foo
The theme supports folders in folders and articles + folders in one folder (see an example inside content). So you can store inside folder another folders and describe in index some specific details.
Pages
A page should be started by
+++
title = "File and folders in folder"
date = 2020-01-18 # or weight
description = "Description"
insert_anchor_links = "right"
[taxonomies] #all taxonomies is optional
tags = ["newtag"]
authors = ["John Doe"]
+++
Zola allows to create drafts:
draft = true
Also, by default you have two taxonomies: tags and authors. It's optional, not necessary to use it on all pages. And you can add your own taxonomy:
- Copy tags or authors folder and rename it to your taxonomy
- Add your taxonomy to config.toml
- Add to page.html template code like
{%/* if page.taxonomies.yourtaxonomynameplural */%}
<ul>
{%/* for tag in page.taxonomies.yourtaxonomynameplural */%}
<li><a href="{{/* get_taxonomy_url(kind="yourtaxonomynameplural", name=yourtaxonomyname) | safe */}}" >{{/* yourtaxonomyname */}}</a></li>
{%/* endfor */%}
</ul>
{%/* endif */%}
Done. I told you Zola is amazing :)
Anyway you can rewrite theme for your own wishes with Zola (link to documentation)