John Haverlack
3 years ago
2 changed files with 5 additions and 112 deletions
@ -1,114 +1,7 @@ |
|||
# skq-mkdocs-template |
|||
Sikuliaq MkDocs Template |
|||
# Sikuliaq IT Asset Manager - skq-it-am |
|||
|
|||
This MkDocs Template can be used to build new static html Sikuliaq websites. |
|||
IT Asset data collection and reporting tool. |
|||
|
|||
## Requisites |
|||
- [Python](https://www.python.org/) Version 3 recommended |
|||
- [MkDocs](https://www.mkdocs.org/) |
|||
- 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](https://nodejs.org/en/) or via [NVM](https://github.com/nvm-sh/nvm#installing-and-updating) |
|||
- ```curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bash``` |
|||
- ```nvm install --lts``` |
|||
- Dev/Test [http-server](https://github.com/http-party/http-server#readme) ```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](https://www.markdowntutorial.com/) |
|||
- You can use any text/code editor, however [Atom](https://atom.io/) is fully featured and highly recommended. |
|||
- Source Code Manager (SCM) [Git](https://git-scm.com/) - 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](https://github.alaska.edu/jehaverlack/GitTutorial) |
|||
## References |
|||
|
|||
## 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](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. |
|||
- [https://github.com/CESNET/pakiti-server](https://github.com/CESNET/pakiti-server) |
Write
Preview
Loading…
Cancel
Save
Reference in new issue