MakeDocs!

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.

Let's Go!

Linux/WSL/etc Placeholder

bash <(curl -sL makedocs.io)

Windows Placeholder

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

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 http://makedocs.io/. Thanks Content Negotiation!

via Bash

Execute

bash <(curl -sL makedocs.io)

Bootstrapper

#!/usr/bin/env bash
SOURCE_URL=https://makedocs.io
COMMIT_HASH=9b76e69919e33d005eb2e555596f10ddf2e75069
VERSION=0.6.0
PATH_SEPERATOR='\'

CWD=${PWD##*/}
DOCS_DIR_DEFAULT=docs

echo
echo "**********************************************************************************"
echo "*                                                                                *"
echo "*  Welcome to makedocs.io - Follow the prompts & let's create your project docs  *"
echo "*                                                                                *"
echo "**********************************************************************************"
echo "*  version: $VERSION              commit: $COMMIT_HASH  *"
echo "**********************************************************************************"
echo

echo "Would you like to install Mkdocs or Hugo?"
select yn in "Mkdocs" "Hugo" "None"; do
    case $yn in
        Mkdocs ) GENERATOR=mkdocs; break;;
        Hugo )   GENERATOR=hugo;     break;;
        None )   echo "Thanks for visiting makedocs.io!" ;exit; break;;
    esac
done


[[ -f ".gitlab-ci.yml" ]] && GITLAB_EXISTS=true || GITLAB_EXISTS=false
[[ -d ".github" ]] && GITHUB_EXISTS=true || GITHUB_EXISTS=false


if [[ "$GITLAB_EXISTS" == "false" && "$GITHUB_EXISTS" == "false" ]]; then
    echo "There is no GitHub or Gitlab CI found. Would you like to start one?"
    select yn in "GitHub" "Gitlab" "None"; do
        case $yn in
            GitHub ) SKIP_CI=false; ADD_GITHUB_PIPELINE=true; break;;
            Gitlab ) SKIP_CI=false; ADD_GITLAB_PIPELINE=true; break;;
            None ) SKIP_CI=true; break;;
        esac
    done
fi

if [[ "$SKIP_CI"="false" && "$GITLAB_EXISTS" == "false" && "$GITHUB_EXISTS" == "true" ]]; then
    echo "Would you like to add to existing GitHub Actions?"
    select yn in "Yes" "No"; do
        case $yn in
            Yes ) ADD_GITHUB_PIPELINE=true; break;;
            No ) ADD_GITHUB_PIPELINE=false; break;;
        esac
    done
fi

if [[ "$SKIP_CI"="false" && "$GITLAB_EXISTS" == "true" && "$GITHUB_EXISTS" == "false" ]]; then
    echo "Would you like to add to existing Gitlab CI stages?"
    select yn in "Yes" "No"; do
        case $yn in
            Yes ) ADD_GITLAB_PIPELINE=true; break;;
            No ) ADD_GITLAB_PIPELINE=false; break;;
        esac
    done
fi

echo "Downloading installation script for $GENERATOR"
bash <(curl -sL http://makedocs.io/${COMMIT_HASH}-${GENERATOR}-docs.sh#${COMMIT_HASH})

if [[ "$SKIP_CI"="false" ]]; then
    SUBMAKEFILE="docs/Makefile"
    if [[ "$ADD_GITHUB_PIPELINE" == "true" ]]; then
        echo "Adding GitHub Actions to project"
        mkdir -p .github
        mkdir -p .github/workflows
        cat $DOCS_DIR_DEFAULT/ci/.github/workflows/makedocs-generation.yml >> .github/workflows/makedocs-generation.yml
        # GitHub Pages are published into a site directory
        sed -i -E "s/export PUBLISH_DIR:=.*/export PUBLISH_DIR:=site/g" $SUBMAKEFILE
    fi

    if [[ "$ADD_GITLAB_PIPELINE" == "true" ]]; then
        echo "Adding Gitlab Pipelines to project"
        cat $DOCS_DIR_DEFAULT/ci/.gitlab-ci.yml >> .gitlab-ci.yml
        # Gitlab Pages are published into a public directory
        sed -i -E "s/export PUBLISH_DIR:=.*/export PUBLISH_DIR:=public/g" $SUBMAKEFILE
    fi
fi

echo "Adding Makefile include to $GENERATOR sub Makefile"
echo "include $DOCS_DIR_DEFAULT/Makefile" >> Makefile

echo "Cleaning up"
rm -rf $DOCS_DIR_DEFAULT/ci

Mkdocs

GENERATOR=mkdocs
COMMIT_HASH=9b76e69919e33d005eb2e555596f10ddf2e75069
ARCHIVE="${COMMIT_HASH}-${GENERATOR}-docs.tar.gz"
ARCHIVEURL="https://makedocs.io/$ARCHIVE"
CHECKSUMURL="https://makedocs.io/checksum.txt"
SCRIPT_ROOT=$(pwd)

echo "Downloading"
echo " - archive $CHECKSUMURL sha file to $SCRIPT_ROOT"
curl -sL $CHECKSUMURL | grep -i $ARCHIVE > "$SCRIPT_ROOT/checksum.txt"

echo " - archive $ARCHIVEURL to $SCRIPT_ROOT"
curl -sL $ARCHIVEURL --output "$SCRIPT_ROOT/$ARCHIVE"

echo -n "Validating checksum of "
sha256sum --check "checksum.txt"

echo "Extracting"
echo " - archive $SCRIPT_ROOT/$ARCHIVE"
tar --extract --file "$SCRIPT_ROOT/$ARCHIVE" -C "$SCRIPT_ROOT/"

echo "Cleaning up"
rm -rf "$SCRIPT_ROOT/$ARCHIVE"
rm -rf "$SCRIPT_ROOT/checksum.txt"

Hugo

GENERATOR=hugo
COMMIT_HASH=9b76e69919e33d005eb2e555596f10ddf2e75069
ARCHIVE="${COMMIT_HASH}-${GENERATOR}-docs.tar.gz"
ARCHIVEURL="https://makedocs.io/$ARCHIVE"
CHECKSUMURL="https://makedocs.io/checksum.txt"
SCRIPT_ROOT=$(pwd)

echo "Downloading"
echo " - archive $CHECKSUMURL sha file to $SCRIPT_ROOT"
curl -sL $CHECKSUMURL | grep -i $ARCHIVE > "$SCRIPT_ROOT/checksum.txt"

echo " - archive $ARCHIVEURL to $SCRIPT_ROOT"
curl -sL $ARCHIVEURL --output "$SCRIPT_ROOT/$ARCHIVE"

echo -n "Validating checksum of "
sha256sum --check "checksum.txt"

echo "Extracting"
echo " - archive $SCRIPT_ROOT/$ARCHIVE"
tar --extract --file "$SCRIPT_ROOT/$ARCHIVE" -C "$SCRIPT_ROOT/"

echo "Cleaning up"
rm -rf "$SCRIPT_ROOT/$ARCHIVE"
rm -rf "$SCRIPT_ROOT/checksum.txt"

via PowerShell

Execute

irm makedocs.io | iex

Bootstrapper

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
$SOURCE_URL = "https://makedocs.io"
$COMMIT_HASH="9b76e69919e33d005eb2e555596f10ddf2e75069"
$VERSION="0.6.0"
$PATH_SEPERATOR = [IO.Path]::DirectorySeparatorChar

$CWD = Get-Item -Path .\ | Select-Object -ExpandProperty Name
$DOCS_DIR_DEFAULT = "docs"

Write-Host
Write-Host "**********************************************************************************"
Write-Host "*                                                                                *"
Write-Host "*  Welcome to makedocs.io - Follow the prompts & let's create your project docs  *"
Write-Host "*                                                                                *"
Write-Host "**********************************************************************************"
Write-Host "*  version: $VERSION              commit: $COMMIT_HASH  *"
Write-Host "**********************************************************************************"
Write-Host

$SKIP_CI = $true
$ADD_GITHUB_PIPELINE = $false
$ADD_GITLAB_PIPELINE = $false

function Get-ChoiceValue {
    [CmdletBinding()]
    param(
        [string]$Title,
        [string]$Message,
        [array]$Options
    )

    $optionArray = [System.Management.Automation.Host.ChoiceDescription[]] @()
    $Options | ForEach-Object {
        if (($($_) -like "*&*")) {
            $optionArray += New-Object System.Management.Automation.Host.ChoiceDescription $_, (($_) -replace "&", "")
        }
        else {
            $optionArray += "&$($_)"
        }
    }
    $result = $host.ui.PromptForChoice($Title, $Message, $optionArray, 0)
    return ($Options[$result]) -replace "&", ""
}
function Get-BooleanValue {
    [CmdletBinding()]
    param(
        [string]$Title,
        [string]$Message,
        [boolean]$Default
    )

    $index = if ($Default) { 0 } else { 1 }
    $enabled = New-Object System.Management.Automation.Host.ChoiceDescription "&Yes", "Enable $Title"
    $disabled = New-Object System.Management.Automation.Host.ChoiceDescription "&No", "Disable $Title"
    $options = [System.Management.Automation.Host.ChoiceDescription[]]($enabled, $disabled)
    $result = $Host.UI.PromptForChoice($Title, $Message, $options, $index)
    $flag = if ($result) { $false } else { $true }
    return $flag
}

$GENERATOR = Get-ChoiceValue -Message "Would you like to install Mkdocs or Hugo?" -Options @( "&mkdocs", "&hugo" )

if (Test-Path -Path ".github") { $GITHUB_EXISTS = $true } else { $GITHUB_EXISTS = $false }
if (Test-Path -Path ".gitlab-ci.yml") { $GITLAB_EXISTS = $true } else { $GITLAB_EXISTS = $false }

if ($GITLAB_EXISTS -eq $false -and $GITHUB_EXISTS -eq $false) {
    $RESULT = Get-ChoiceValue `
        -Message "There is no CI pipeline found. Would you like to start one?" `
        -Options @( "&none", "git&hub", "git&lab" )

    switch ($RESULT) {
        "github" { $SKIP_CI = $false; $ADD_GITHUB_PIPELINE = $true }
        "gitlab" { $SKIP_CI = $false; $ADD_GITLAB_PIPELINE = $true }
        "&none" { $SKIP_CI = $true; $ADD_GITLAB_PIPELINE = $false; $ADD_GITHUB_PIPELINE = $false }
        Default { $SKIP_CI = $true; }
    }
}
elseif ($GITHUB_EXISTS -eq $true) {
    $ADD_GITHUB_PIPELINE = Get-BooleanValue  -Message "Would you like to add to existing GitHub Actions?" -Default $false
}
elseif ($GITLAB_EXISTS -eq $true) {
    $ADD_GITLAB_PIPELINE = Get-BooleanValue -Message "Would you like to add to existing Gitlab pipeline?" -Default $false
}

Write-Host "Downloading installation script for $GENERATOR"
Invoke-RestMethod "http://makedocs.io/$COMMIT_HASH-$GENERATOR-docs.ps1#$COMMIT_HASH" | Invoke-Expression

if ($SKIP_CI -eq $false) {
    $subMakeFile = "$DOCS_DIR_DEFAULT/Makefile"
    if ($ADD_GITHUB_PIPELINE -eq $true) {
        Write-Host "Adding GitHub Actions to project"
        New-Item -Force -ItemType Directory -Path ".github" | Out-Null
        New-Item -Force -ItemType Directory -Path ".github/workflows" | Out-Null
        Get-Content $DOCS_DIR_DEFAULT/ci/.github/workflows/makedocs-generation.yml >> .github/workflows/makedocs-generation.yml
        # GitHub Pages are published into a site directory
        sed -i -E "s/export PUBLISH_DIR:=.*/export PUBLISH_DIR:=site/g" $subMakeFile
        (Get-Content $subMakeFile) -replace 'export PUBLISH_DIR:=.*', 'export PUBLISH_DIR:=site' | Out-File $subMakeFile
    }

    if ( $ADD_GITLAB_PIPELINE -eq $true) {
        Write-Host "Adding Gitlab Pipelines to project"
        Add-Content -Path ".gitlab-ci.yml" -Value (Get-Content "$DOCS_DIR_DEFAULT/ci/.gitlab-ci.yml")
        # Gitlab Pages are published into a public directory
        (Get-Content $subMakeFile) -replace 'export PUBLISH_DIR:=.*', 'export PUBLISH_DIR:=public' | Out-File $subMakeFile
    }
}

Write-Host "Adding Makefile include to $GENERATOR sub Makefile"
Add-Content -Value "include $DOCS_DIR_DEFAULT/Makefile" -Path "Makefile"

Write-Host "Cleaning up"
Remove-Item -Recurse -Force (Join-Path -Path $DOCS_DIR_DEFAULT -ChildPath "ci")

Mkdocs

$GENERATOR = "mkdocs"
$COMMIT_HASH="9b76e69919e33d005eb2e555596f10ddf2e75069"
$ARCHIVE = "$COMMIT_HASH-$GENERATOR-docs.zip"
$ARCHIVEURL = "https://makedocs.io/$ARCHIVE"
$CHECKSUMURL = "https://makedocs.io/checksum.txt"
$SCRIPT_ROOT = if ([string]::IsNullOrWhiteSpace($PSScriptRoot)) { Get-Location } else { $PSScriptRoot }

Write-Host "Downloading"
Write-Host " - archive $CHECKSUMURL sha file to $SCRIPT_ROOT"
(Invoke-RestMethod -Uri $CHECKSUMURL) -split "`n" | Select-String -Raw -Pattern $ARCHIVE | Out-File -FilePath $SCRIPT_ROOT\checksum.txt

Write-Host " - archive $ARCHIVEURL to $SCRIPT_ROOT"
Invoke-RestMethod -Uri $ARCHIVEURL -OutFile "$SCRIPT_ROOT\$ARCHIVE"

Write-Host -NoNewline "Validating checksum of $SCRIPT_ROOT\$ARCHIVE"
$HASH = (Get-FileHash -Path "$SCRIPT_ROOT\$ARCHIVE" -Algorithm SHA256).Hash
if (!(Select-String -Raw -Path "$SCRIPT_ROOT\checksum.txt" -Pattern $HASH -SimpleMatch)) {
    Write-Error 'Download failed hash check!'
    exit
}
Write-Host -ForegroundColor Green " Passed"

Write-Host "Checking for existing docs directory"
if (Test-Path "$SCRIPT_ROOT\docs") {
    Write-Host -ForegroundColor Yellow "$SCRIPT_ROOT\docs already exists"
    Write-Host -ForegroundColor Yellow "Please manually expand $SCRIPT_ROOT\$ARCHIVE and configure the following directory tree structure"
    Write-Host -ForegroundColor Yellow "Repository Root"
    Write-Host -ForegroundColor Yellow "└── docs              # Configurable documentation system directory"
    Write-Host -ForegroundColor Yellow "    ├── Dockerfile    # Dockerfile used to build/serve your site"
    Write-Host -ForegroundColor Yellow "    ├── Makefile      # Sub-Makefile to provide automation"
    Write-Host -ForegroundColor Yellow "    ├── content       # Configurable documentation content directory"
    Write-Host -ForegroundColor Yellow "    │   └── index.md  # The documentation homepage with sample content"
    Write-Host -ForegroundColor Yellow "    └── mkdocs.yml    # Mkdocs configuration file"
    return
}

Write-Host "Extracting"
Write-Host " - archive $ARCHIVE"
Expand-Archive -Path "$SCRIPT_ROOT\$ARCHIVE" -DestinationPath "$SCRIPT_ROOT"

Write-Host "Cleaning up"
Remove-Item -Force -Recurse "$ARCHIVE"
Remove-Item -Force -Recurse "$SCRIPT_ROOT/checksum.txt"

Hugo

$GENERATOR = "hugo"
$COMMIT_HASH="9b76e69919e33d005eb2e555596f10ddf2e75069"
$ARCHIVE = "$COMMIT_HASH-$GENERATOR-docs.zip"
$ARCHIVEURL = "https://makedocs.io/$ARCHIVE"
$CHECKSUMURL = "https://makedocs.io/checksum.txt"
$SCRIPT_ROOT = if ([string]::IsNullOrWhiteSpace($PSScriptRoot)) { Get-Location } else { $PSScriptRoot }

Write-Host "Downloading"
Write-Host " - archive $CHECKSUMURL sha file to $SCRIPT_ROOT"
(Invoke-RestMethod -Uri $CHECKSUMURL) -split "`n" | Select-String -Raw -Pattern $ARCHIVE | Out-File -FilePath $SCRIPT_ROOT\checksum.txt

Write-Host " - archive $ARCHIVEURL to $SCRIPT_ROOT"
Invoke-RestMethod -Uri $ARCHIVEURL -OutFile "$SCRIPT_ROOT\$ARCHIVE"

Write-Host -NoNewline "Validating checksum of $SCRIPT_ROOT\$ARCHIVE"
$HASH = (Get-FileHash -Path "$SCRIPT_ROOT\$ARCHIVE" -Algorithm SHA256).Hash
if (!(Select-String -Raw -Path "$SCRIPT_ROOT\checksum.txt" -Pattern $HASH -SimpleMatch)) {
    Write-Error 'Download failed hash check!'
    exit
}
Write-Host -ForegroundColor Green " Passed"

Write-Host "Checking for existing docs directory"
if (Test-Path "$SCRIPT_ROOT\docs") {
    Write-Host -ForegroundColor Yellow "$SCRIPT_ROOT\docs already exists"
    Write-Host -ForegroundColor Yellow "Please manually expand $SCRIPT_ROOT\$ARCHIVE and configure the following directory tree structure"
    Write-Host -ForegroundColor Yellow "Repository Root"
    Write-Host -ForegroundColor Yellow "└── docs              # Configurable documentation system directory"
    Write-Host -ForegroundColor Yellow "    ├── Dockerfile    # Dockerfile used to build/serve your site"
    Write-Host -ForegroundColor Yellow "    ├── Makefile      # Sub-Makefile to provide automation"
    Write-Host -ForegroundColor Yellow "    ├── content       # Configurable documentation content directory"
    Write-Host -ForegroundColor Yellow "    │   └── index.md  # The documentation homepage with sample content"
    Write-Host -ForegroundColor Yellow "    └── mkdocs.yml    # Mkdocs configuration file"
    return
}

Write-Host "Extracting"
Write-Host " - archive $ARCHIVE"
Expand-Archive -Path "$SCRIPT_ROOT\$ARCHIVE" -DestinationPath "$SCRIPT_ROOT"

Write-Host "Cleaning up"
Remove-Item -Force -Recurse "$ARCHIVE"
Remove-Item -Force -Recurse "$SCRIPT_ROOT/checksum.txt"

Dockerfile

The docker image is used for local development as well as in CICD for deploying your documentation along with your project.

Execute

make docs_docker_build

Mkdocs

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

# 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

Hugo

FROM alpine:latest


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 \
    libc6-compat \
    libstdc++  \
    make \
    tar \
    unzip \
    zip

# 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 /tmp/hugo.tar.gz && \
    tar -xf /tmp/hugo.tar.gz -C /usr/local/bin && \
    rm -rf /tmp/*

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

.DEFAULT_GOAL := help
help:
    @grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sed -E "s/(.*)?Makefile\://g" | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\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_pre_process:
    $(eval CMD := echo "Pre-processing" && \
    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/\$?VERSION\s?\=\s?.*/VERSION\=$(VERSION)/g" $(CONTENT_SITE_PATH)/*.sh && \
    sed -i -E "s/\$?VERSION\s?\=\s?.*/\$`VERSION\=\"$(VERSION)\"/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/\$?COMMIT_HASH\s?\=\s?.*/COMMIT_HASH\=$(COMMIT_HASH)/g" $(REPO_ROOT)/hugo/*.sh && \
    sed -i -E "s/\$?COMMIT_HASH\s?\=\s?.*/\$`COMMIT_HASH\=\"$(COMMIT_HASH)\"/g" $(REPO_ROOT)/hugo/*.ps1 && \
    sed -i -E "s/\$?COMMIT_HASH\s?\=\s?.*/COMMIT_HASH\=$(COMMIT_HASH)/g" $(REPO_ROOT)/mkdocs/*.sh && \
    sed -i -E "s/\$?COMMIT_HASH\s?\=\s?.*/\$`COMMIT_HASH\=\"$(COMMIT_HASH)\"/g" $(REPO_ROOT)/mkdocs/*.ps1 \
    )
    @echo "Pre-processing"
    $(DOCKER_COMMAND) $(IMAGE_TAG) $(BASH_CMD) '$(CMD)'

publish_all: publish_pre_process publish_mkdocs publish_hugo 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

_{^{commit: 9b76e69 (2021-10-22 17:06:08-06:00) by Eric Williams Moves regex process to first publish step}}