Initial public project release

975bbe21 · Eric Williams · 975bbe21 · 975bbe21 · 975bbe21 · 975bbe21
Commit 975bbe21 authored Oct 12, 2021 by Eric Williams
--- a/.editorconfig
+++ b/.editorconfig
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+# Unix-style newlines with a newline ending every file
+[*]
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*]
+end_of_line = lf
+
+# Trim tailing whitespace
+trim_trailing_whitespace = true
+
+# Tab indentation (no size specified)
+[Makefile]
+indent_style = tab
--- a/.gitignore
+++ b/.gitignore
+env/
+processed/*
+site.zip
+site/
+processed/
+*.terraform/
+*terraform.tfstate*
+tf.plan
+variables.tfvars
+**/public/*
+.vscode/*
+CHANGELOG
+**/*.tar.gz
+**/*.zip
+test/*
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
+variables:
+  TF_ROOT: ${CI_PROJECT_DIR}/terraform
+  TF_ADDRESS: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/${CI_PROJECT_NAME}
+  TF_VAR_cloudflare_email: ${CLOUDFLARE_EMAIL}
+  TF_VAR_cloudflare_api_key: ${CLOUDFLARE_API_KEY}
+  TF_VAR_cloudflare_zone_id: ${CLOUDFLARE_ZONE_ID}
+  TF_VAR_a_record_name: ${A_RECORD_NAME}
+  TF_VAR_a_record_value: ${A_RECORD_VALUE}
+  TF_VAR_cname_record_name: ${CNAME_RECORD_NAME}
+  TF_VAR_cname_record_value: ${CNAME_RECORD_VALUE}
+  TF_VAR_account_id: ${ACCOUNT_ID}
+  TF_VAR_script_config_uri: ${SCRIPT_CONFIG_URI}
+  DOCKER_HOST: tcp://docker:2376
+  DOCKER_TLS_CERTDIR: "/certs"
+
+cache:
+  key: production
+  paths:
+    - ${TF_ROOT}/.terraform
+
+stages:
+  - prepare
+  - validate
+  - build
+  - deploy
+
+terraform_init:
+  image: registry.gitlab.com/gitlab-org/terraform-images/stable:latest
+  stage: prepare
+  before_script:
+    - cd ${TF_ROOT}
+  script:
+    - gitlab-terraform init
+  rules:
+    - if: $CI_COMMIT_TAG
+      changes:
+        - terraform/main.tf
+
+terraform_validate:
+  image: registry.gitlab.com/gitlab-org/terraform-images/stable:latest
+  stage: validate
+  before_script:
+    - cd ${TF_ROOT}
+  script:
+    - gitlab-terraform init
+    - gitlab-terraform validate
+  rules:
+    - if: $CI_COMMIT_TAG
+      changes:
+        - terraform/main.tf
+
+terraform_plan:
+  image: registry.gitlab.com/gitlab-org/terraform-images/stable:latest
+  stage: build
+  before_script:
+    - cd ${TF_ROOT}
+  script:
+    - gitlab-terraform plan
+    - gitlab-terraform plan-json
+  artifacts:
+    name: plan
+    paths:
+      - ${TF_ROOT}/plan.cache
+    reports:
+      terraform: ${TF_ROOT}/plan.json
+  rules:
+    - if: $CI_COMMIT_TAG
+      changes:
+        - terraform/main.tf
+
+terraform_apply:
+  image: registry.gitlab.com/gitlab-org/terraform-images/stable:latest
+  stage: deploy
+  before_script:
+    - cd ${TF_ROOT}
+  script:
+    - gitlab-terraform apply
+  needs: [terraform_plan]
+  rules:
+    - if: $CI_COMMIT_TAG
+      changes:
+        - terraform/main.tf
+
+docker_build_makedocs:
+  image: docker:latest
+  stage: build
+  services:
+    - docker:dind
+  before_script:
+    - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY
+    - apk add --no-cache build-base
+  script:
+    - |
+      tag='latest'
+      cd $CI_PROJECT_DIR
+      IMAGE_TAG="$CI_REGISTRY_IMAGE/makedocs:${tag}"
+      docker build --pull -t $IMAGE_TAG .
+      docker push $IMAGE_TAG
+  rules:
+    - if: $CI_COMMIT_TAG
+      changes:
+        - Dockerfile
+
+docker_build_makedocs_hugo:
+  image: docker:latest
+  stage: build
+  services:
+    - docker:dind
+  before_script:
+    - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY
+    - apk add --no-cache build-base
+  script:
+    - |
+      tag='latest'
+      cd $CI_PROJECT_DIR/hugo
+      IMAGE_TAG="$CI_REGISTRY_IMAGE/hugo:${tag}"
+      docker build --pull -t $IMAGE_TAG .
+      docker push $IMAGE_TAG
+  rules:
+    - if: $CI_COMMIT_TAG
+      changes:
+        - hugo/Dockerfile
+
+docker_build_makedocs_mkdocs:
+  image: docker:latest
+  stage: build
+  services:
+    - docker:dind
+  before_script:
+    - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY
+    - apk add --no-cache build-base
+  script:
+    - |
+      tag='latest'
+      cd $CI_PROJECT_DIR/mkdocs
+      IMAGE_TAG="$CI_REGISTRY_IMAGE/mkdocs:${tag}"
+      docker build --pull -t $IMAGE_TAG .
+      docker push $IMAGE_TAG
+  rules:
+    - if: $CI_COMMIT_TAG
+      changes:
+        - mkdocs/Dockerfile
+
+changelog:
+  image: docker:latest
+  stage: build
+  services:
+    - docker:dind
+  script:
+    - echo "No change log entries to show at this time" > CHANGELOG
+    - docker run --rm --env _GIT_LIMIT=366 --env _GIT_LOG_OPTIONS="--ignore-all-space --ignore-blank-lines" -v $(pwd):/git arzzen/git-quick-stats /bin/bash -c "git-quick-stats -c | tail -n +4 | uniq | tee CHANGELOG"
+  artifacts:
+    paths:
+      - CHANGELOG
+  rules:
+    - if: $CI_COMMIT_TAG || $CI_COMMIT_BRANCH
+
+pages:
+  needs:
+    - job: changelog
+    - job: terraform_apply
+      optional: true
+    - job: docker_build_makedocs
+      optional: true
+  image: $CI_REGISTRY_IMAGE/makedocs:latest
+  stage: deploy
+  services:
+    - docker:dind
+  variables:
+    SITE_NAME: "MakeDocs!"
+    DOMAIN_NAME: makedocs.io
+    SITE_URL: http://$DOMAIN_NAME
+    PROTOCOL: https
+    COMMIT_HASH: $CI_COMMIT_SHA
+    REPO_URL: $CI_PROJECT_URL
+  script:
+    - printenv | sort
+    - ls -lah /usr/local/bin/
+    - make publish_all
+    # - sha256sum public/*-public.* | sed -E "s/public\///g" > public/checksum.txt
+    # - sha256sum public/*-docs.*   | sed -E "s/public\///g" >> public/checksum.txt
+  artifacts:
+    paths:
+      - public/
+  rules:
+    - if: $CI_COMMIT_TAG || $CI_COMMIT_BRANCH
--- a/Dockerfile
+++ b/Dockerfile
+FROM alpine:latest
+
+ENV PYTHONUNBUFFERED=1
+ENV TZ=US/Mountain
+RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone
+
+RUN apk update && \
+    apk add --update bash \
+    ca-certificates \
+    curl \
+    docker-cli \
+    dos2unix \
+    git \
+    gnupg \
+    make \
+    py3-pip \
+    python3 \
+    tar \
+    zip
+
+# # # Docker apt repo
+# # RUN curl -fsSL https://download.docker.com/linux/debian/gpg | apt-key add -
+# # RUN add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/debian $(lsb_release -cs) stable"
+# # RUN apk update && apk install -y docker-ce docker-ce-cli
+
+# # https://www.mkdocs.org/ https://mkdocs-macros-plugin.readthedocs.io/ https://squidfunk.github.io/mkdocs-material/
+RUN pip3 install --no-cache --upgrade pip setuptools
+RUN pip3 install mkdocs mkdocs-macros-plugin mkdocs-material
+
+RUN FILE=theme.list && \
+    echo 'mkdocs'      >> /$FILE && \
+    echo 'readthedocs' >> /$FILE && \
+    echo 'material'    >> /$FILE
+
+# //TODO setup this repo to be a pip package
+RUN cd /tmp && \
+    git clone https://gitlab.com/motowilliams/mkdocs-macros-file-include.git && \
+    cd mkdocs-macros-file-include && \
+    python3 setup.py install && \
+    cd / && \
+    rm -rf /tmp/
+
+# these used to be added as files - heredocs would be useful but we don't know
+#  if the users CI / local setup will support it
+RUN echo "Creating wrapper scripts"                                         && \
+    SCRIPT=/usr/local/bin/build                                             && \
+    echo '#!/usr/bin/env bash'                                   >> $SCRIPT && \
+    echo                                                         >> $SCRIPT && \
+    echo 'echo "Setting directory to $DOCS_SRC_PATH"'            >> $SCRIPT && \
+    echo 'cd $DOCS_SRC_PATH'                                     >> $SCRIPT && \
+    echo                                                         >> $SCRIPT && \
+    echo 'echo "Building documentation site"'                    >> $SCRIPT && \
+    echo 'mkdocs build'                                          >> $SCRIPT && \
+    chmod 755 $SCRIPT                                                       && \
+    SCRIPT=/usr/local/bin/serve                                             && \
+    echo '#!/usr/bin/env bash'                                   >> $SCRIPT && \
+    echo                                                         >> $SCRIPT && \
+    echo 'echo "Setting directory to $DOCS_SRC_PATH"'            >> $SCRIPT && \
+    echo 'cd $DOCS_SRC_PATH'                                     >> $SCRIPT && \
+    echo                                                         >> $SCRIPT && \
+    echo 'echo "Serving documentation site on port $LOCAL_PORT"' >> $SCRIPT && \
+    echo 'mkdocs serve -v --dev-addr=0.0.0.0:$LOCAL_PORT'        >> $SCRIPT && \
+    chmod 755 $SCRIPT
+
+RUN SCRIPT=/usr/local/bin/semver && \
+    curl -sL https://raw.githubusercontent.com/fsaintjacques/semver-tool/3.2.0/src/semver --output $SCRIPT && \
+    chmod 755 $SCRIPT
+
+# Hugo install
+ENV HUGO_VERSION="0.88.1"
+RUN curl -sL https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_Linux-64bit.tar.gz --output hugo_${HUGO_VERSION}.tar.gz && \
+    tar -xf hugo_${HUGO_VERSION}.tar.gz -C /usr/local/bin && \
+    rm -rf hugo_${HUGO_VERSION}.tar.gz
+
+COPY ./hugo/new-site.sh /usr/local/bin/new-hugo-site
+RUN chmod 755 /usr/local/bin/new-hugo-site
+
+COPY ./mkdocs/new-site.sh /usr/local/bin/new-mkdocs-site
+RUN chmod 755 /usr/local/bin/new-mkdocs-site
+
+RUN adduser --disabled-password --gecos '' genericuser
+USER genericuser
--- a/LICENSE
+++ b/LICENSE
+MIT License
+
+Copyright (c) 2021 Eric Williams
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
--- a/Makefile
+++ b/Makefile
+.DEFAULT_GOAL := help
+help:
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | grep -i 'docs_' | sed -E "s/(.*)?Makefile\://g" | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
+
+export DOCS_DIR_NAME ?= content
+export DOCS_SRC ?= docs
+export PUBLISH_DIR ?= public
+export REPO_URL ?= https://example.com/repo
+export SITE_DIR ?= site
+export SITE_NAME ?= Sample-Site
+export PROTOCOL ?= http
+export DOMAIN_NAME ?= 127.0.0.1:8000
+export SITE_URL ?= $(PROTOCOL)://$(DOMAIN_NAME)/
+export LOCAL_PORT ?= 8000
+
+ifeq ($(OS),Windows_NT)
+SHELL := '/usr/bin/sh.exe'
+PWD := $(shell sh.exe -c pwd)
+else
+SHELL := /bin/bash
+endif
+
+export BASH_CMD := $(SHELL) -c
+export COMMIT_HASH ?= $(shell [[ -d ".git" ]] && git rev-parse HEAD)
+export SHORT_COMMIT_HASH ?= $(shell [[ -d ".git" ]] && git rev-parse --short HEAD)
+export REPO_ROOT := $(shell [[ -n "${CI}" ]] && echo $(PWD) || echo '/app' )
+export VERSION ?= $(shell [[ -d ".git" ]] && git tag --sort=v:refname | grep -E '[0-9]' | tail -1 || echo 0.0.0)
+
+export IMAGE_NAME ?= makedocsio
+export IMAGE_VERSION ?= latest
+export IMAGE_TAG = $(IMAGE_NAME):$(IMAGE_VERSION)
+export ADDITIONAL_BUILD_ARGS ?=
+
+export DOCS_SRC_PATH=$(REPO_ROOT)/$(DOCS_SRC)
+export PUBLISH_PATH := $(REPO_ROOT)/$(PUBLISH_DIR)
+
+export CONTENT_SITE_PATH=$(DOCS_SRC_PATH)/$(DOCS_DIR_NAME)
+export DOCS_SITE_PATH=$(DOCS_SRC_PATH)/$(SITE_DIR)
+
+ifdef CI
+	export IMAGE_TAG=
+	export DOCKER_COMMAND :=
+else
+	export DOCKER_COMMAND := docker run -it \
+		-v $(PWD):$(REPO_ROOT) \
+		--env CI=TRUE \
+		--env COMMIT_HASH=$(COMMIT_HASH) \
+		--env COMMIT_HASH_LENGTH=$(COMMIT_HASH_LENGTH) \
+		--env CONTENT_SITE_PATH=$(CONTENT_SITE_PATH) \
+		--env DOCS_DIR=$(DOCS_DIR_NAME) \
+		--env DOCS_SITE_PATH=$(DOCS_SITE_PATH) \
+		--env DOCS_SRC_PATH=$(DOCS_SRC_PATH) \
+		--env LOCAL_PORT=$(LOCAL_PORT) \
+		--env PUBLISH_PATH=$(PUBLISH_PATH) \
+		--env REPO_ROOT=$(REPO_ROOT) \
+		--env REPO_URL=$(REPO_URL) \
+		--env SITE_DIR=$(SITE_DIR) \
+		--env SITE_NAME="$(SITE_NAME)" \
+		--env SITE_URL=$(SITE_URL) \
+		--name $(IMAGE_NAME) \
+		--rm
+endif
+
+bump_patch:
+	$(eval CMD := semver bump patch $(VERSION) )
+	@BUMP=$(shell $(DOCKER_COMMAND) $(IMAGE_TAG) $(BASH_CMD) '$(CMD)') && \
+	echo "Bumping version from $(VERSION) to $$BUMP" && \
+	git tag -a -m "$$BUMP" $$BUMP
+
+docker_build:
+	docker build --pull $(ADDITIONAL_BUILD_ARGS) -t $(IMAGE_TAG) . -f Dockerfile
+
+debug: ## Runs the docker image interactively for debugging purposes
+	@$(DOCKER_COMMAND) $(ADDITIONAL_BUILD_ARGS) $(IMAGE_TAG) $(CMD)
+
+clean_makedocsio:
+	$(eval CMD := \
+	mkdir -p $(REPO_ROOT)/public && rm -rf $(REPO_ROOT)/public/* && \
+	rm -rf $(REPO_ROOT)/hugo/*-hugo-docs.tar.gz && rm -rf $(REPO_ROOT)/hugo/*-hugo-docs.zip && \
+	rm -rf $(REPO_ROOT)/mkdocs/*-mkdocs-docs.tar.gz && rm -rf $(REPO_ROOT)/mkdocs/*-mkdocs-docs.zip && \
+	rm -rf $(DOCS_SITE_PATH) \
+	)
+	@echo "Cleaning $(SITE_DIR).zip & $(SITE_DIR) in $(SITE_DIR)"
+	$(DOCKER_COMMAND) $(IMAGE_TAG) $(BASH_CMD) '$(CMD)'
+
+build_makedocsio:
+	$(eval CMD := echo "Starting build" && \
+	build && \
+	cp /theme.list $(DOCS_SITE_PATH)/ && \
+	echo "Post build processing complete" \
+	)
+	@echo "Building"
+	$(DOCKER_COMMAND) $(IMAGE_TAG) $(BASH_CMD) '$(CMD)'
+
+publish_post_process:
+	$(eval CMD := echo "Postprocessing" && \
+	sed -i -E "s/\$?SOURCE_URL\s?\=\s?.*/SOURCE_URL\=$(PROTOCOL)\:\/\/$(DOMAIN_NAME)/g" $(CONTENT_SITE_PATH)/*.sh && \
+	sed -i -E "s/\$?SOURCE_URL\s?\=\s?.*/\$`SOURCE_URL\ = \"$(PROTOCOL)\:\/\/$(DOMAIN_NAME)\"/g" $(CONTENT_SITE_PATH)/*.ps1 && \
+	sed -i -E "s/\$?COMMIT_HASH\s?\=\s?.*/COMMIT_HASH\=$(COMMIT_HASH)/g" $(CONTENT_SITE_PATH)/*.sh && \
+	sed -i -E "s/\$?COMMIT_HASH\s?\=\s?.*/\$`COMMIT_HASH\=\"$(COMMIT_HASH)\"/g" $(CONTENT_SITE_PATH)/*.ps1 && \
+	sed -i -E "s/\$?VERSION\s?\=\s?.*/VERSION\=$(VERSION)/g" $(CONTENT_SITE_PATH)/*.sh && \
+	sed -i -E "s/\$?VERSION\s?\=\s?.*/\$`VERSION\=\"$(VERSION)\"/g" $(CONTENT_SITE_PATH)/*.ps1 \
+	)
+	@echo "Building"
+	$(DOCKER_COMMAND) $(IMAGE_TAG) $(BASH_CMD) '$(CMD)'
+
+publish_all: publish_mkdocs publish_hugo publish_post_process publish_makedocsio
+	$(eval CMD := cd $(REPO_ROOT)/public && sha256sum *-docs.* > checksum.txt)
+	$(DOCKER_COMMAND) $(IMAGE_TAG) $(BASH_CMD) '$(CMD)'
+
+publish_makedocsio: build_makedocsio
+	$(eval CMD := \
+	mkdir -p $(PUBLISH_PATH) && \
+	cp -R $(DOCS_SITE_PATH)/* $(PUBLISH_PATH)/ && \
+	echo "Publishing" \
+	)
+	$(DOCKER_COMMAND) $(IMAGE_TAG) $(BASH_CMD) '$(CMD)'
+
+publish_mkdocs:
+	$(eval CMD := \
+	cd $(REPO_ROOT)/mkdocs && \
+	new-mkdocs-site $(COMMIT_HASH) && \
+	mkdir -p $(REPO_ROOT)/public && \
+	cp -f $(REPO_ROOT)/mkdocs/*mkdocs-docs.* $(REPO_ROOT)/public/ && \
+	mv $(REPO_ROOT)/public/mkdocs-docs.ps1   $(REPO_ROOT)/public/$(COMMIT_HASH)-mkdocs-docs.ps1 && \
+	mv $(REPO_ROOT)/public/mkdocs-docs.sh    $(REPO_ROOT)/public/$(COMMIT_HASH)-mkdocs-docs.sh \
+	)
+	$(DOCKER_COMMAND) $(IMAGE_TAG) $(BASH_CMD) '$(CMD)'
+
+publish_hugo:
+	$(eval CMD := \
+	cd $(REPO_ROOT)/hugo && \
+	new-hugo-site $(COMMIT_HASH) && \
+	mkdir -p $(REPO_ROOT)/public && \
+	cp -f $(REPO_ROOT)/hugo/*hugo-docs.* $(REPO_ROOT)/public/ && \
+	mv $(REPO_ROOT)/public/hugo-docs.ps1   $(REPO_ROOT)/public/$(COMMIT_HASH)-hugo-docs.ps1 && \
+	mv $(REPO_ROOT)/public/hugo-docs.sh    $(REPO_ROOT)/public/$(COMMIT_HASH)-hugo-docs.sh \
+	)
+	$(DOCKER_COMMAND) $(IMAGE_TAG) $(BASH_CMD) '$(CMD)'
+
+package_makedocs:
+	$(eval CMD := cd $(DOCS_SRC_PATH) && zip -r ../$(SITE_DIR).zip ./)
+	@echo "Packaging"
+	$(DOCKER_COMMAND) $(IMAGE_TAG) $(BASH_CMD) '$(CMD)'
+
+serve_makedocsio:
+	$(eval CMD := serve)
+	$(DOCKER_COMMAND) -p $(LOCAL_PORT):$(LOCAL_PORT) --expose $(LOCAL_PORT) $(IMAGE_TAG) $(BASH_CMD) '$(CMD)'
+
+create_changelog:
+	echo "No change log entries to show at this time" > CHANGELOG && \
+    docker run --rm --env _GIT_LIMIT=366 --env _GIT_LOG_OPTIONS="--ignore-all-space --ignore-blank-lines" -v $(PWD):/git arzzen/git-quick-stats /bin/bash -c "git-quick-stats -c | tail -n +4 | uniq | tee CHANGELOG"
+
+print-%: ; @echo $*=$($*)
+
+printenv:
+	printenv | sort
--- a/README.md
+++ b/README.md
+# makedocs
--- a/docs/content/changelog.md
+++ b/docs/content/changelog.md
+# Changelog
+
+```
+{{ include_file('../CHANGELOG','') }}
+```
--- a/docs/content/img/bash.png
+++ b/docs/content/img/bash.png
--- a/docs/content/img/powershell.png
+++ b/docs/content/img/powershell.png
--- a/docs/content/index.md
+++ b/docs/content/index.md
+# {{ config.site_name }}
+
+Creating docs for software projects is not glamorous. MakeDocs will help you get started with some simple docs quickly and easily. It is just some tooling, scripts really, to ask you a couple of questions combined with some cursory inspection of your repo to get you started with a static site generator under some build infrastructure.
+
+This will install a copy of the toolchain needed to create docs. Afterwards you can adjust anything required to make it work better in your project.
+
+!!! tip "Let's Go!"
+    Linux/WSL/etc
+    ![Placeholder](img/bash.png){align=left}
+    ``` bash
+    bash <(curl -sL makedocs.io)
+    ```
+
+    Windows
+    ![Placeholder](img/powershell.png){align=left}
+    ``` powershell
+    irm makedocs.io | iex
+    ```
+
+## How Does It Work?
+
+You execute the installation script for MakeDocs from one of the above commands. It will prompt you to choose a generator, check your repository for existing GitHub Actions or Gitlab Pipelines or ask to install new CICD templates.
+
+Afterwards we grab a package related to your selections and install the generator with optional automation files.
+
+### Flows
+
+``` mermaid
+sequenceDiagram
+    participant makedocs.io
+    participant Terminal
+    participant Script
+    participant Repo
+    Terminal->>makedocs.io: Hello makedocs.io
+    Terminal->>makedocs.io: I am not a browser
+    makedocs.io->>Terminal: Html? No, take a script!
+    Terminal->>Script: Do your thing!
+    Script->>Terminal: What static site generator would you like?
+    Terminal->>Script: "Mkdocs or Hugo"
+    Script->>Terminal: Would you like to install CICD pipelines?
+    Terminal->>Script: "Always!"
+    Script->>Repo: Let's do this!
+    activate Repo
+    Script-->>Repo: Downloads package
+    Script-->>Repo: Installs CICD pipelines files
+    deactivate Repo
+    Script->>Terminal: All done!
+    Terminal-->Terminal: make docs_docker_build
+    Terminal-->Terminal: make docs_build
+    Terminal-->Terminal: make docs_serve
+```
+
+### Project layout
+
+Using all the defaults for the installation this is what the new additions to your source tree will look like!
+
+    ├─ Makefile                   # Appended include statement for the sub-Makefile
+    └─ docs                       # Configurable documentation system directory
+        ├─ Dockerfile             # Dockerfile used to build/serve your site
+        ├─ Makefile               # Sub-Makefile to provide automation
+        ├─ docs|content           # Documentation site content directory
+        │   └─ index.md           # The documentation homepage with sample content
+        └─ mkdocs.yml|config.toml # Static site's configuration file
+
+### The Scripts
+
+You can either download the scripts below or just run them from our url at {{ config.site_url }}. <a href="https://en.wikipedia.org/wiki/Content_negotiation" target="_blank">Thanks Content Negotiation!</a>
+
+#### via Bash
+
+=== "Execute"
+
+    ``` bash
+    bash <(curl -sL makedocs.io)
+    ```
+
+=== "Script"
+
+    ``` bash
+    {{ include_file('content/init.sh','    ') }}
+    ```
+
+#### via PowerShell
+
+=== "Execute"
+
+    ``` powershell
+    irm makedocs.io | iex
+    ```
+
+=== "Script"
+
+    ``` powershell
+    {{ include_file('content/init.ps1','    ') }}
+    ```
+
+## Dockerfile
+
+The docker image is used for local development as well as in CICD for deploying your documentation along with your project.
+
+=== "Execute"
+
+    ``` bash
+    make docs_docker_build
+    ```
+
+=== "Dockerfile"
+
+    ``` Dockerfile
+    {{ include_file('../Dockerfile','    ') }}
+    ```
+
+## Build it with Make
+
+Part of the installation is the addition of a sub-make file. This wraps all the tasks needed to build, serve and publish your docs. We will add a small include in your root Makefile if we detect one.
+
+=== "Execute"
+
+    | Make Command      | Description                                                        |
+    | ----------------- | ------------------------------------------------------------------ |
+    | docs_build        | Builds the content to the 'site' directory                         |
+    | docs_clean        | Removes the content artifacts directories and archive              |
+    | docs_debug        | Runs the docker image interactively for debugging purposes         |
+    | docs_docker_build | Build the docker image used for these make targets not within DIND |
+    | docs_package      | Builds the content to a compressed archive                         |
+    | docs_publish      | Builds the content to the 'PUBLISH_DIR' directory                  |
+    | docs_serve        | Runs the static site generation server                             |
+
+=== "Makefile"
+
+    ``` Makefile