Creating GitHub README.md Documentation Using Snippets

Are you looking to streamline the creation of your GitHub README.md documentation? Let’s leverage snippets and automation to ensure consistency, accuracy, and efficiency across your projects.

Here's a quick guide on how to use a Bash script to automate the process of building your README.md from multiple markdown files and generating a Table of Contents (TOC).

Imagine you have a document source tree with multiple snippets in smaller files to make editing and re-arrangement easier e.g.

source/
├── 000_introduction.md
├── 010_making_it_easy.md
├── 020_the_basics.md
├── 030_culture.md
├── 040_documentation.md
├── 050_Operations.md
├── 060_Processes.md
├── 070_VCS.md
├── 080_Development_environments.md
├── 800_Useful_links.md
└── 999_Outro.md        

example 000_introduction.md

# This is my README. There are many like it, but this one is mine.

Author: Martin Jackson - [@actionjack](https://twitter.com/actionjack)

## Introduction

My README is my best friend. It is my life. I must master it as I must master my life.        

example 010_making_it_easy.md

## Without me, my README is useless

Without my README, I am useless. I must write my README true.        

Bash Script for README.md Creation

This script concatenates multiple markdown files, ensures each has a newline at the end, and generates a TOC using Docker.

#!/bin/bash

guide="README.md"

add_newline() {
  file="$1"
  last_char=$(tail -c 1 "$file" 2>/dev/null)

  # Check if the last character is not a newline
  if [ "$last_char" != "" ]; then
    echo "" >> "$file"
    echo "Added a newline to $file"
  fi
}

add_newline_to_md() {
  for file in source/*.md
    do add_newline ${file}
  done
}

build_guide() {
  cat source/*.md > ${guide}
}

generate_toc () {
  docker run --rm \
    --volume "$(pwd)":/app \
    peterdavehello/npm-doctoc doctoc /app/${guide}
}

main () {
  add_newline_to_md
  build_guide
  generate_toc
}

main "$@"
        

How It Works

1. Add Newline to Markdown Files: Ensures each markdown file in the source directory ends with a newline.
2. Build Guide: Concatenates all markdown files into a single README.md.
3. Generate TOC: Uses Docker to run doctoc and automatically generate a Table of Contents.

Benefits

• Consistency: Ensures all documentation follows a standard format.
• Efficiency: Automates repetitive tasks, saving valuable time.
• Accuracy: Reduces errors by automating the newline addition and TOC generation.
• Ease of Maintenance: Make's it easier to add or insert new sections of documentation and re-arrange documentation as needed.

Integrate this script into your workflow to enhance your project's documentation quality and readability. For working example and other handy scripts, check out ActionJack’s repository.

Happy documenting! ????

#DevOps #Documentation #GitHub #Readme #Automation #Snippets #BashScript #TechTips #EngineeringExcellence