Skip to content

- MkDocs

1. What is MkDocs?

MkDocs is a useful library that automates the coding process when creating simple web pages.

2. Features of MKDocs

  • Can create web pages even if you cannot write HTML or CSS (knowledge of HTML and CSS is required if you want to make detailed arrangements)
  • Text is written in markdown format
  • There are theme (website design) templates that make it easy to create beautiful web pages.
  • Design arrangements can be managed with a simple description on a single yaml file
  • html files can be output and users can immediately use the web page

3. The flow of Installing MkDocs

I learned and installed as same as Setting up MkDocs on fabcloud

  1. Installed Homebrew (version 3.6.17)
    from here-> Homebrew
  2. Installed Python (version: 3.11.1)
  3. Installed pip (version 22.3.1)
  4. Installed Mkdocs (version 1.4.2)

4. Customize Mkdocs

To make the Mkdocs much easier to see, I refer to useful links MkDocs Themes and configuration for MkDocs . Then, I changed file of mkdocs.yml　as flow.

4-1) Installed Theme "material"

I installed the theme of Material for MkDocs with pip:

pip install mkdocs-material

4-2) Customize MkDocs

I edit and add the lines to file of mkdocs.yml as follows.

alt text

sample code

site_name: Hiroe Takeda - Fab Academy

site_dir: "public"

theme:
  name: material

  features:
  - content.code.copy

  palette:
    primary: teal
    scheme: slate

# Copyright
copyright: Copyright © 2023 Hiroe Takeda - Creative Commons Attribution Non Commercial

5. Command of MkDocs (at lease)

Create new project（NOTE：project name　→ xxxxxx）

mkdocs new xxxxx

Change current directory to xxxxxx folder

cd xxxxx

Build the project

mkdocs build

Start server

mkdocs serve

Output to HTML file

mkdocs build

NOTE:
Shutting down the local server, Ctrl+C in a running terminal

6. Editing the text

When editing the text, add and edit the file (extension:*.md).
< Example > alt text