stitchmd

README

stitchmd

• Introduction
  • Getting Started
  • Installation
  • GitHub Action
• Usage
  • Options
  • Syntax
• Advanced
  • Page Titles
  • Including summaries
• License

Introduction

stitchmd is a tool that stitches together several Markdown files into one large Markdown file, making it easier to maintain larger Markdown files.

It lets you define the layout of your final document in a summary file, which it then uses to stitch and interlink other Markdown files with.

See Getting Started for a tutorial, or Usage to start using it.

Features

• Cross-linking: Recognizes cross-links between files and their headers and re-targets them for their new locations. This keeps your input and output files independently browsable on websites like GitHub.

  Example

  Input

  [Install](install.md) the program.
  See also, [Overview](#overview).
  

  Output

  [Install](#install) the program.
  See also, [Overview](#overview).
  

• Relative linking: Rewrites relative images and links to match their new location.

  Example

  Input

  ![Graph](images/graph.png)
  

  Output

  ![Graph](docs/images/graph.png)
  

• Header offsetting: Adjusts levels of all headings in included Markdown files based on the hierarchy in the summary file.

  Example

  Input

  - [Introduction](intro.md)
    - [Installation](install.md)
  

  Output

  # Introduction
  
  <!-- contents of intro.md -->
  
  ## Installation
  
  <!-- contents of install.md -->
  

Use cases

The following is a non-exhaustive list of use cases where stitchmd may come in handy.

• Maintaining a document with several collaborators with reduced risk of merge conflicts.
• Divvying up a document between collaborators by ownership areas. Owners will work inside the documents or directories assigned to them.
• Keeping a single-page and multi-page version of the same content.
• Re-using documentation across multiple Markdown documents.
• Preparing initial drafts of long-form content from an outline of smaller texts.

...and more. (Feel free to contribute a PR with your use case.)

Getting Started

This is a step-by-step tutorial to introduce stitchmd.

For details on how to use it, see Usage.

1. First, install stitchmd. If you have Go installed, this is as simple as:

   go install go.abhg.dev/stitchmd@latest
   

   For other installation methods, see the Installation section.

2. Create a couple Markdown files. Feel free to open these up and add content to them.

   echo 'Welcome to my program.' > intro.md
   echo 'It has many features.' > features.md
   echo 'Download it from GitHub.' > install.md
   

   Alternatively, clone this repository and copy the doc folder.

3. Create a summary file defining the layout between these files.

   cat > summary.md << EOF
   - [Introduction](intro.md)
     - [Features](features.md)
   - [Installation](install.md)
   EOF
   

4. Run stitchmd on the summary.

   stitchmd summary.md
   

   The output should look similar to the following:

   - [Introduction](#introduction)
     - [Features](#features)
   - [Installation](#installation)
   
   # Introduction
   
   Welcome to my program.
   
   ## Features
   
   It has many features.
   
   # Installation
   
   Download it from GitHub.
   

   Each included document got its own heading matching its level in the summary file.

5. Next, open up intro.md and add the following to the bottom:

   See [installation](install.md) for instructions.
   

   If you run stitchmd now, the output should change slightly.

   - [Introduction](#introduction)
     - [Features](#features)
   - [Installation](#installation)
   
   # Introduction
   
   Welcome to my program.
   See [installation](#installation) for instructions.
   
   ## Features
   
   It has many features.
   
   # Installation
   
   Download it from GitHub.
   

   stitchmd recognized the link from intro.md to install.md, and updated it to point to the # Installation header instead.

Next steps: Play around with the document further:

• Alter the hierarchy further.

• Add an item to the list without a file:

  - Overview
    - [Introduction](intro.md)
    - [Features](features.md)
  

• Add sections or subsections to a document and link to those.

  [Build from source](install.md#build-from-source).
  

• Add a heading to the summary.md:

  # my awesome program
  
  - [Introduction](#introduction)
    - [Features](#features)
  - [Installation](#installation)
  

Installation

You can install stitchmd from pre-built binaries or from source.

Binary installation

Pre-built binaries of stitchmd are available for different platforms over a few different mediums.

Homebrew

If you use Homebrew on macOS or Linux, run the following command to install stitchmd:

brew install abhinav/tap/stitchmd

ArchLinux

If you use ArchLinux, install stitchmd from AUR using the stitchmd-bin package.

git clone https://aur.archlinux.org/stitchmd-bin.git
cd stitchmd-bin
makepkg -si

If you use an AUR helper like yay, run the following command instead:

yay -S stitchmd-bin

GitHub Releases

For other platforms, download a pre-built binary from the Releases page and place it on your $PATH.

Install from source

To install stitchmd from source, install Go >= 1.20 and run:

go install go.abhg.dev/stitchmd@latest

GitHub Action

stitchmd-action is a GitHub Action that will install and run stitchmd for you in CI. With stitchmd-action, you can set up GitHub Workflows to:

• Validate that your output file is always up-to-date

  uses: abhinav/stitchmd-action@v1
  with:
    mode: check
    summary: doc/SUMMARY.md
    output: README.md
  

• Automatically update your output file based on edits

  uses: abhinav/stitchmd-action@v1
  with:
    mode: write
    summary: doc/SUMMARY.md
    output: README.md
  
  # Optionally, use https://github.com/stefanzweifel/git-auto-commit-action
  # to automatically push these changes.
  

• Install a binary of stitchmd and implement your own behavior

  uses: abhinav/stitchmd-action@v1
  with:
    mode: install
  

For more information, see stitchmd-action.

Usage

stitchmd [OPTIONS] FILE

stitchmd accepts a single Markdown file as input. This file defines the layout you want in your combined document, and is referred to as the summary file.

For example:

# User Guide

- [Getting Started](getting-started.md)
    - [Installation](installation.md)
- [Usage](usage.md)
- [API](api.md)

# Appendix

- [How things work](implementation.md)
- [FAQ](faq.md)

The format of the summary file is specified in more detail in Syntax.

Given such a file as input, stitchmd will print a single Markdown file including the contents of all listed files inline.

Example output

The output of the input file above will be roughly in the following shape:

# User Guide

- [Getting Started](#getting-started)
    - [Installation](#installation)
- [Usage](#usage)
- [API](#api)

## Getting Started

<!-- contents of getting-started.md -->

### Installation

<!-- contents of installation.md -->

## Usage

<!-- contents of usage.md -->

## API

<!-- contents of api.md -->

# Appendix

- [How things work](#how-things-work)
- [FAQ](#faq)

## How things work

<!-- contents of implementation.md -->

## FAQ

<!-- contents of faq.md -->

Options

stitchmd supports the following options:

• -preface FILE
• -offset N
• -no-toc
• -o FILE
• -C DIR
• -d

Read from stdin

Instead of reading from a specific file on-disk, you can pass in '-' as the file name to read the summary from stdin.

cat summary.md | stitchmd -

Add a preface

-preface FILE

If this flag is specified, stitchmd will include the given file at the top of the output verbatim.

You can use this to add comments holding license headers or instructions for contributors.

For example:

cat > generated.txt <<EOF
<!-- This file was generated by stitchmd. DO NOT EDIT. -->

EOF
stitchmd -preface generated.txt summary.md

Offset heading levels

-offset N

stitchmd changes heading levels based on a few factors:

• level of the section heading
• position of the file in the hierarchy of that section
• the file's own title heading

The -offset flag allows you to offset all these headings by a fixed value.

Example

Input

# User Guide

- [Introduction](intro.md)
  - [Installation](install.md)

stitchmd -offset 1 summary.md

Output

## User Guide

- [Introduction](#introduction)
  - [Installation](#installation)

### Introduction

<!-- ... -->

### Installation

<!-- ... -->

Use a negative value to reduce heading levels.

Example

Input

# User Guide

- [Introduction](intro.md)
  - [Installation](install.md)

stitchmd -offset -1 summary.md

Output

# User Guide

- [Introduction](#introduction)
  - [Installation](#installation)

# Introduction

<!-- ... -->

## Installation

<!-- ... -->

Disable the TOC

-no-toc

stitchmd reproduces the original table of contents in the output. You can change this with the -no-toc flag.

stitchmd -no-toc summary.md

This will omit the item listing under each section.

Example

Input

- [Introduction](intro.md)
- [Installation](install.md)

stitchmd -no-toc summary.md

Output

# Introduction

<!-- .. -->

# Installation

<!-- .. -->

Write to file

-o FILE

stitchmd writes its output to stdout by default. Use the -o option to write to a file instead.

stitchmd -o README.md summary.md

Change the directory

-C DIR

Paths in the summary file are considered relative to the summary file.

Use the -C flag to change the directory that stitchmd considers itself to be in.

stitchmd -C docs summary.md

This is especially useful if your summary file is passed via stdin

... | stitchmd -C docs -

Report a diff

-d

stitchmd normally writes output directly to the file if you pass in a filename with -o. Use the -d flag to instead have it report what would change in the output file without actually changing it.

stitchmd -d -o README.md # ...

This can be useful for lint checks and similar, or to do a dry run and find out what would change without changing it.

Syntax

Although the summary file is Markdown, stitchmd expects it in a very specific format.

The summary file is comprised of one or more sections. Sections have a section title specified by a Markdown heading.

Example

# Section 1

<!-- contents of section 1 -->

# Section 2

<!-- contents of section 2 -->

If there's only one section, the section title may be omitted.

File = Section | (SectionTitle Section)+

Each section contains a Markdown list defining one or more list items. List items are one of the following, and may optionally have another list nested inside them to indicate a hierarchy.

• Links to local Markdown files: These files will be included into the output, with their contents adjusted to match their place.

  Example

  - [Overview](overview.md)
  - [Getting Started](start/install.md)
  

• Inclusions of other summary files: These are links in the form ![title](file.md). The included file will be read as another summary file, and its sections will nested under this heading.

  Example

  - ![FAQ](faq.md)
  

• Plain text: These will become standalone headers in the output. These must have a nested list.

  Example

  - Introduction
      - [Overview](overview.md)
      - [Getting Started](start/install.md)
  

• External links: These will be written in the generated table-of-contents verbatim. They cannot have other items nested inside them.

  Example

  - [Overview](overview.md)
  - [Community](https://example.com)
  

Items listed in a section are rendered together under that section. A section is rendered in its entirety before the listing for the next section begins.

Example

Input

# Section 1

- [Item 1](item-1.md)
- [Item 2](item-2.md)

# Section 2

- [Item 3](item-3.md)
- [Item 4](item-4.md)

Output

# Section 1

- [Item 1](#item-1)
- [Item 2](#item-2)

## Item 1

<!-- ... -->

## Item 2

<!-- ... -->

# Section 2

- [Item 3](#item-3)
- [Item 4](#item-4)

## Item 3

<!-- ... -->

## Item 4

<!-- ... -->

The heading level of a section determines the minimum heading level for included documents: one plus the section level.

Example

Input

## User Guide

- [Introduction](intro.md)

Output

## User Guide

- [Introduction](#introduction)

### Introduction

<!-- ... -->

Advanced

Page Titles

All pages included with stitchmd are assigned a title.

By default, the title is the name of the item in the summary. For example, given the following:

<!-- summary.md -->
- [Introduction](intro.md)

<!-- intro.md -->
Welcome to Foo.

The title for intro.md is "Introduction".

Output

- [Introduction](#introduction)

# Introduction

Welcome to Foo.

A file may specify its own title by adding a heading that meets the following rules:

• it's a level 1 heading
• it's the first item in the file
• there are no other level 1 headings in the file

If a file specifies its own title, this does not affect its name in the summary list. This allows the use of short link titles for long headings.

For example, given the following:

<!-- summary.md -->
- [Introduction](intro.md)

<!-- intro.md -->
# Introduction to Foo

Welcome to Foo.

The title for intro.md will be "Introduction to Foo".

Output

- [Introduction](#introduction-to-foo)

# Introduction to Foo

Welcome to Foo.

Including summary files

List items in the following form are requests to include another summary file:

- ![title](file.md)

The list defined in the included summary file will be nested under this item. For example, given the following:

<!-- use/summary.md -->

- [Installation](install.md)
- [Configuration](config.md)

<!-- maintain/summary.md -->

- [Dashboard](dashboard.md)
- [Troubleshooting](troubleshooting.md)

A joint summary file could take the form:

- ![Usage](use/summary.md)
- ![Maintenance](maintain/summary.md)

Output

- [Usage](#usage)
  - [Installation](#installation)
  - [Configuration](#configuration)
- [Maintenance](#maintenance)
  - [Dashboard](#dashboard)
  - [Troubleshooting](#troubleshooting)

# Usage

## Installation

<!-- ... -->

## Configuration

<!-- ... -->

# Maintenance

## Dashboard

<!-- ... -->

## Troubleshooting

<!-- ... -->

Markdown files referenced in the included summary files are relative to the summary file. In the example above, the file tree would be:

.
|- summary.md
|- use
|  |- summary.md
|  |- install.md
|  '- config.md
'- maintain
   |- summary.md
   |- dashboard.md
   '- troubleshooting.md

Limitations of included summary files:

• It is an error to define more than one section in an included summary file.
• The section title's heading level does not affect the level of items defined in that summary file. The position of the included file in the parent file determines levelling.

License

This software is distributed under the GPL-2.0 License:

stitchmd
Copyright (C) 2023 Abhinav Gupta

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

Documentation

Overview

stitchmd reads a Markdown file defining a table of contents with links to other Markdown files, and reduces it all to a single Markdown file.

See README for more details.