create github pages with mkdocs¶

overview¶

use mkdocs-material for github repo page
use webStackLaravel for github user pages

prerequisite¶

tools to install (windows)¶

software	download link	comments
docker	https://hub.docker.com/editions/community/docker-ce-desktop-windows/
git	https://git-scm.com/download/win	(gui) https://desktop.github.com/
vscode	https://code.visualstudio.com/	editing config/scripts/bash
typora	https://typora.io/	writing in markdown
powershell	come with windows	'docker run' with volume mounting

setup github¶

create a folder on pc for the repo¶

mkdir <gitfolder>

create an account on github and a repo¶

https://github.com/

https://help.github.com/en/github/getting-started-with-github/create-a-repo

ssh-keygen
(can change default key name from id_rsa to eg. id_rsa_<account>)

if not using id_rsa as key name, add to ~/.ssh/config to use the certain key

Host github.com-<account>
  Hostname github.com
  User <account>
  IdentityFile ~/.ssh/id_rsa_<account>

add ~/.ssh/id_rsa_sl.pub to github¶

https://help.github.com/en/github/authenticating-to-github/adding-a-new-ssh-key-to-your-github-account

init the repo and link to github¶

cd <gitfolder>
git init
git add .
git commit -m "init"
git remote add origin git@github.com-<account>:<account>/<repo>.git
git push -u origin master

git push --set-upstream origin master (optional; tochk)

create/publish static webpage¶

https://squidfunk.github.io/mkdocs-material/getting-started/

https://www.mkdocs.org

create customized docker image (optional)¶

create working folder¶

cd /<docker folder>/mcdocs

create Dockerfile¶

FROM python:3.8.1-alpine3.11

# Set build directory
WORKDIR /tmp

# Copy files necessary for build
COPY material material
COPY MANIFEST.in MANIFEST.in
COPY package.json package.json
COPY README.md README.md
COPY requirements.txt requirements.txt
COPY setup.py setup.py
COPY docker-entrypoint.sh /bin/docker-entrypoint.sh

# Perform build and cleanup artifacts
RUN \
  apk add --no-cache \
    git \
    git-fast-import \
    openssh \
  && pip install --no-cache-dir . \
  && pip install --no-cache-dir \
    'mkdocs-minify-plugin>=0.2' \
    'mkdocs-git-revision-date-localized-plugin>=0.4' \
    'mkdocs-awesome-pages-plugin>=2.2.1' \
  && rm -rf /tmp/* \
  # added by vt
  && mkdir /root/.ssh \
  && chmod +x /bin/docker-entrypoint.sh

# Set working directory
WORKDIR /docs

# Expose MkDocs development server port
EXPOSE 8000

# Start development server by default
ENTRYPOINT ["/bin/docker-entrypoint.sh"]
CMD ["serve", "--dev-addr=0.0.0.0:8000"]

create docker-entrypoint.sh¶

#!/bin/sh
set -e

cp -R /tmp/.ssh/* /root/.ssh
chmod 700 /root/.ssh
cd /root/.ssh
chmod 644 `ls | grep pub`
chmod 600 `ls | grep id | grep -v pub`

cd /docs
exec mkdocs "$@"

git pull original mkdocs-material repo to another folder, eg. //others/¶

cd /<gitfolder>/others
git clone https://github.com/squidfunk/mkdocs-material.git

cp required folders to /¶

cd /<gitfolder>/others/mkdocs-material
cp -r material /<docker folder>/mkdocs/
cp MANIFEST.in /<docker folder>/mkdocs/
cp package.json /<docker folder>/mkdocs/
cp README.md /<docker folder>/mkdocs/
cp requirements.txt /<docker folder>/mkdocs/
cp setup.py /<docker folder>/mkdocs/

build image¶

cd /<docker folder>/mkdocs
docker image rm mkdocs:v1 (optional, to remove old tag if exists)
docker build . -t mkdocs:v1

submit image to dockerhub (optional)¶

docker tag mkdocs:v1 <dockerhub account name>/mkdocs-material:v1
docker push <dockerhub account name>/mkdocs-material:v1

create mkdocs.yml and "docs" folder¶

change to the repo folder¶

cd <gitfolder>

edit mkdocs.yml¶

original from mkdoc-material

# Project information
site_name: <xxx>
site_url: https://<account>.github.io/<repo>/
site_author: <name>
site_description: >-
  Writing is the best way of learning
# Repository
repo_name: <account>/<repo>
repo_url: https://github.com/<account>/<learn>
edit_uri: ""

# Copyright
copyright: Copyright &copy; 2018 - 2020 <name> 

# Configuration
theme:
  name: material

  # 404 page
  static_templates:
    - 404.html

  # Don't include MkDocs' JavaScript
  include_search_page: false
  search_index_only: true

  # Default values, taken from mkdocs_theme.yml
  language: en
  features:
    - tabs
    #- instant
  palette:
    primary: indigo
    accent: indigo
  font:
    text: Roboto
    code: Roboto Mono
  icon:
    logo: logo
  favicon: assets/favicon.png

# Plugins
plugins:
  - search
  - minify:
      minify_html: true
  - awesome-pages

# Customization
extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/<account>
    - icon: fontawesome/brands/gitter
      link: https://gitter.im/<account>
    - icon: fontawesome/brands/docker
      link: https://hub.docker.com/r/<account>
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/<account>
    - icon: fontawesome/brands/linkedin
      link: https://linkedin.com/in/<account>
    - icon: fontawesome/brands/instagram
      link: https://instagram.com/<account>

# Extensions
markdown_extensions:
  - markdown.extensions.admonition
  - markdown.extensions.attr_list
  - markdown.extensions.codehilite:
      guess_lang: false
  - markdown.extensions.def_list
  #- markdown.extensions.footlearn
  - markdown.extensions.meta
  - markdown.extensions.toc:
      permalink: true
  - pymdownx.arithmatex
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret
  - pymdownx.critic
  - pymdownx.details
  - pymdownx.emoji:
      emoji_index: !!python/name:pymdownx.emoji.twemoji
      emoji_generator: !!python/name:pymdownx.emoji.to_svg
  # - pymdownx.highlight:
  #     linenums_style: pymdownx-inline
  - pymdownx.inlinehilite
  - pymdownx.keys
  - pymdownx.magiclink:
      repo_url_shorthand: true
      user: squidfunk
      repo: mkdocs-material
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.snippets:
      check_paths: true
  - pymdownx.superfences
  - pymdownx.tabbed
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde

# Google Analytics
google_analytics:
  - !!python/object/apply:os.getenv ["GOOGLE_ANALYTICS_KEY"]
  - auto

create docs folder (the actual files written are inside this folder)¶

mkdir docs
cd docs
echo "first doc" > readme.md

modify mkdocs.yml (optional)¶

change colo
choose font: https://fonts.google.com

host the webpage locally¶

start up container with docker run¶

it seemed using sh script to wrap "docker run" doesn't work with volume mapping (;C being added to foldername)

https://forums.docker.com/t/weird-error-under-git-bash-msys-solved/9210

docker run -d --name mkdocs --restart always -p 8000:8000 -v <gitfolder>/docs:/docs -v ~/.ssh:/tmp/.ssh mkdocs:v1

docker run -d --name mkdocs-v2 --restart always -p 8082:8000 -v <gitfolder>/docs:/docs -v ~/.ssh:/tmp/.ssh mkdocs-material:v2

browser to the webpage¶

http://localhost:8000

publish to github manually¶

docker exec -it mkdocs sh

build and public¶

mkdocs gh-deploy

browser to github page¶

https://<account>.github.io/<repo>

auto publish via travis.io¶

prerequisite¶

create account and link to github and enable sync the repo¶

https://docs.travis-ci.com/user/tutorial/

create github token¶

https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line

configure¶

add github token as env variable to travis repo setting¶

https://docs.travis-ci.com/user/deployment/pages/

add .travis.yml to the repo folder, eg. /d/github/stocklifelearn/learn¶

language: python # Set the build language to Python
python: 3.6 # Set the version of Python to use
branches: master # Set the branch to build from

install: # Install the required dependencies; optional: mkdocs-material-extensions
  - pip install mkdocs mkdocs-material pymdown-extensions pygments mkdocs-git-revision-date-localized-plugin mkdocs-minify-plugin mkdocs-awesome-pages-plugin

script: true # Skip script (Don't use this if one already exists)
before_deploy:
  - mkdocs build --verbose --clean --strict # Build a local version of the docs

deploy: # Deploy documentation to Github in the gh_pages branch
  provider: pages
  skip_cleanup: true
  github_token: $github_token
  local_dir: site
  on:
    branch: master

start writing some files in "docs" folder and push to github¶

git add .
git commit -m "some commit notes"
git push

debug¶

check on the process on travis.io¶

https://travis-ci.org/dashboard

links¶

font¶

https://www.awwwards.com/20-best-web-fonts-from-google-web-fonts-and-font-face.html

create github pages with mkdocs¶

overview¶

prerequisite¶

tools to install (windows)¶

setup github¶

create a folder on pc for the repo¶

create an account on github and a repo¶

create ssh key to login with user/passwd¶

add ~/.ssh/id_rsa_sl.pub to github¶

init the repo and link to github¶

create/publish static webpage¶

create customized docker image (optional)¶

create working folder¶

create Dockerfile¶

create docker-entrypoint.sh¶

git pull original mkdocs-material repo to another folder, eg. //others/¶

cp required folders to /¶

build image¶

submit image to dockerhub (optional)¶

create mkdocs.yml and "docs" folder¶

change to the repo folder¶

edit mkdocs.yml¶

create docs folder (the actual files written are inside this folder)¶

modify mkdocs.yml (optional)¶

host the webpage locally¶

start up container with docker run¶

browser to the webpage¶

publish to github manually¶

login container¶

build and public¶

browser to github page¶

auto publish via travis.io¶

prerequisite¶

create account and link to github and enable sync the repo¶

create github token¶

configure¶

add github token as env variable to travis repo setting¶

add .travis.yml to the repo folder, eg. /d/github/stocklifelearn/learn¶

start writing some files in "docs" folder and push to github¶

debug¶

check on the process on travis.io¶

links¶

font¶