skq-it-am/web/root

skq-mkdocs-template

Sikuliaq MkDocs Template

This MkDocs Template can be used to build new static html Sikuliaq websites.

Requisites

• Python Version 3 recommended
• MkDocs
  • NOTE: on some Linux systems and Macs you may need pip3 for python3 instead of pip in the following commands.
  • sudo pip install mkdocs
  • sudo pip install mkdocs-pdf-export-plugin
  • sudo pip install mkdocs-bootstrap
  • sudo pip install https://github.com/mitya57/python-markdown-math/archive/master.zip
  • You will need MkDocs version 1.1 To test: mkdocs --version
  • If you have an older version, try upgrading with: sudo pip3 install -U mkdocs
• Node.js or via NVM
  • curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bash
  • nvm install --lts
• Dev/Test http-server npm install --global http-server (Requires Node.js)
  • http-server is not required but provides a handy light weight web server for testing sites on your local computer.
• Learning Markdown
• You can use any text/code editor, however Atom is fully featured and highly recommended.
• Source Code Manager (SCM) Git - While not necessary to build MkDocs sites Git is highly recommended to manage website content over time.
  • This site has an introduction to using Git https://github.alaska.edu/jehaverlack/GitTutorial

Cloning a new site

You will need a UA Github (github.alaska.edu) account for the following:

git clone https://github.alaska.edu/skq/skq-mkdocs-template.git

cd skq-mkdocs-template

You will find the following directory structure:

skq-mkdocs-template/
├── custom (Custom HTML Libraries and Theme Styles)
├── docs (Site content source files)
├── mkdocs.yml (Master Configuration File)
├── README.md (This README.md doc)
└── site (MkDocs Generated Static HTML Site Files)

Building the site

You will need to build your site after editing content or the configuration.

mkdocs build --clean

After building your static HTML site will be in the site directory

Testing the site

To test your site, run the http-server that was installed with Node.js/NPM

http-server site

Point your browser to http://localhost:8080

Create a New Page

touch docs/newpage.md

Edit the Markdown Code in your docs/newpage.md file:

# New Page

This is my new page

Edit the site config

Edit mkdocs.yml

Edit the Menu

You will need to add your newpage.md to the navigation menu in mkdocs.yml

nav:
  - <span class="fas fa-home"></span>: index.md
  - Setup:
    - Install: install.md
    - Optional Tool: optional.md
    - Cloning Site: cloning.md
    - Build Site: build.md
    - Testing Site: test.md
    - Editing Content: editing.md
  - Features:
    - Search: search.md
    - Swipe Nav: swipe.md
    - Version: version.md
    - Menu Nav: menu.md
    - Code: code.md
    - Equations: equations.md
    - Footnotes: footnotes.md
    - Icons: icons.md
    - Bootstrap: bootstrap.md
    - PDF: pdf.md
  - About:
    - Contact: contact.md
    - NewPage: newpage.md

Next rebuild and reload the site in your browser.