Setup MKDOCS for GreenEarthOS repo

PLoiya commented 3 years ago

Overview

we need to setup mkdocs for in order to build a wiki for publicising our project research

Action Items

[ ] Install mkdocs into GreenEarthOS repo
[ ] Document any configurational settings - option/details, in a comment on this issue

Resources/Instructions

Sample to refer https://brigade.cloud/

JasonEb commented 3 years ago

I have setup the GreenEarthOS repo with mkdocks with this pull request. Please let me know if there's anything I need to revise and review.

Mkdocs is a python pip package. It can be installed individually but I opted to start a requirements.txt package for future python packages to add to the project.

I have updated the repo readme.md with Installation instructions and requirements. Additionally I added some sample test pages in the /docs folder for reference.

Usage

Mkdocs requires an index.md file in the docs folder and a mkdocs.yml in the root. To run a local development server, use mkdocs serve which will have hot reloading on code changes.

Customization

Most of the configuration starts with the mkdocs.yml file. For theming, there is

theme:
  name: material
  features:
    - navigation.tabs
  palette:
    primary: "red"
    accent: "blue"

Additionally there is a sizable collection of mkdocs themes at https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes.

Thers are the more basic configurations. However there are advanced customizations where one can pull additional css or js files.

extra_javascript:
  - https://unpkg.com/mermaid@8.5.0/dist/mermaid.min.js

extra_css:
  - https://use.fontawesome.com/releases/v5.13.0/css/all.css

There is a healthy plug-in ecosystem for mkdocs.

plugins:
  - search
  - awesome-pages

These plug-ins are collected here https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins. Notable ones are the translation and localization plug-ins in my opinion.

Finally there are markdown_extensions for additional documentation tools.

markdown_extensions:
  - admonition
  - codehilite:
      linenums: true
  - pymdownx.inlinehilite
  - pymdownx.tasklist:
      custom_checkbox: true

These ones are examples of creating code block friendly text, creating diagrams with markdown syntax, or generating a table of contents functionality. Extensions can be viewed here https://python-markdown.github.io/extensions/

ExperimentsInHonesty commented 3 years ago

@JasonEb I pointed the domain name at the folder docs instead of the root, but instead of loading the content from https://github.com/hackforla/GreenEarthOS/blob/main/docs/index.md it gave a 404. So something was not operating correctly. Given that the GreenEarthOS meeting is after the ops meeting, and it seems like the ops meeting is going long. Maybe you and I can review this after the ops meeting ends. Or you can meet Puneet and I on Fridays at 6pm PDT. Let us know which works for you and we will try to walk through this next week.

JasonEb commented 3 years ago

@JasonEb I pointed the domain name at the folder docs instead of the root, but instead of loading the content from https://github.com/hackforla/GreenEarthOS/blob/main/docs/index.md it gave a 404. So something was not operating correctly. Given that the GreenEarthOS meeting is after the ops meeting, and it seems like the ops meeting is going long. Maybe you and I can review this after the ops meeting ends. Or you can meet Puneet and I on Fridays at 6pm PDT. Let us know which works for you and we will try to walk through this next week.

Sorry @ExperimentsInHonesty and @PLoiya, I wasn't as available as I thought during the end of the week. I'm exploring the issue now and will correspond on Slack.

PLoiya commented 2 years ago

Thanks @JasonEb for your help. we will reachout to you if need any help in future.

hackforla / GreenEarthOS