Getting started¶
The documentation is based on markdown files
in order to create a new documents (page) you can use any online editor like Stackedit or as recommended use VS code
Out of the box supports .md also, press Ctrl+Shift+V to have a real time viewer.
Might find Markdown Cheatsheet useful.
Create, Update, Delete a document¶
You can edit the files directly on github then push your changes or clone the repo locally then make your changes and push.
Option one - Github directly¶
head to the repo here , make sure that you have the permission to the repo, see The folder structure
Option two - Clone¶
clone the documentation repo
git clone https://github.com/developers412/CitiesOS_Docs.git
The folder structure¶
.
├── .github
├── workflows
├── ci.yml # defining the automated build process.
├── docs # here are all the documents.
├── assets # here all the images / icons you reference from any document.
newDocument.md # You can create a doc
├── Group # creating a folder uses the sub files as group
anotherDoc.md
├── mkdocs.yml # here are the whole site configurations.
Create, update, delete documents from the docs folder then push your changes to the main it will be deployed here shortly (~1 minute Avg)
Example document¶
to follow the theme you need to add those lines at the beginning of the document
Example.md
---
template: overrides/main.html
title: Title of (browser tab/TOC)
---
---
disqus: <shortname>
---
# Some H1
including an image from the assets
including youtube video (link)
[](https://www.youtube.com/watch?v=YOUTUBE_VIDEO_ID_HERE)
example
[](https://www.youtube.com/watch?v=TtSMz-_h_cw)
View the document locally¶
Run the following commands with a terminal in the root folder
pip install -r requirements.txt
pip install material
pip install mkdocs-redirects
mkdocs serve
you should have the following response like
[00:00:47] Serving on http://127.0.0.1:8000/
the documentation should be available on http://localhost:8000/