Migrating to Doks
A light hugo theme supporting navigation bar and night mode.
1. Preparation
2. A new site
2.1 Renaming of the project
Extract the doks project. Rename the doks directory as your site name. Then change to the root of the site directory.
2.2 Dependencies
npm install
Add this line to .npmrc file if behind a proxy.
https-proxy = http://example.com:port
2.3 Development server
npm run start
Now start browser and visit http://localhost:1313. Saved changes will live reload in the browser.
3. Directory Structure
Here we only focus at these 4 directories.
config, content, layouts and static.
3.1 config
_default
- config.toml
Set permalinks.
For example, use slug in url,
[permalinks]
blog = "/:year/:month/:slug/"
Click for more options.
- menus.toml
Add site menus (at top bar) in [[main]]. Add docs menus (at left bar) in [[docs]]. Set social infos in [[social]].
Click for more details.
- paras.toml
Set site title, color, footer, etc.
production
Set baseurl for final publication.
3.2 content
xxx.md
Put all the articles (Markdown format) here.
Start like this,
---
title: "Migrating to Doks"
contributors: []
description: ""
date: 2021-04-04
lastmod:
draft: false
images: []
slug: doks
description: ""
lead: "A light hugo theme supporting navigation bar and night mode"
menu:
docs:
parent: "blog"
---
Set menu:docs: to add this post to the left bar, and parent is consistent with [[docs]] in menus.toml in 3.1.
_index.md
Each sub-directory need an _index.md which describes basic infos about the current directory.
This file is needed for list items and works with list.html in directory layouts.
For example,
---
title: "Blog"
description: "Blog"
date: 2021-04-03
lastmod: 2021-04-03
draft: false
images: []
url: /
---
here, I also set the url of blog section as the index.
3.3 layouts
These are templates for the generation of static html files.
You may customize the index page through the index.html file.
Each sub-directory in 3.2 content requires a sub-directory here with the same name, and put list.html and single.html into that.
The list.html is used for item listing, and single.html for each article (like navigation side bar).
Click for more details.
3.4 static
Put your images, attachments and other static files here. They can be directly accessed with baseurl.
4. Deployment
Now you are ready to publish your site.
Check baseurl in production in 3.1 config.
At the root project directory, type
hugo
and all static files are generated in public directory.
They can be hosted with Nginx, Apache HTTP Server or other web servers.