stitchmd

• Introduction
• Getting Started
• Installation
• GitHub Action
• Usage
• Options
  • Read from stdin
  • Add a preface
  • Offset heading levels
  • Disable the TOC
  • Write to file
  • Change the directory
  • Report a diff
• Syntax
• Advanced
• Page Titles
• Absorbing headings
• 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

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

Output

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

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

Example

Input

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

Output

markdown ![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

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

Output

```markdown # Introduction

## Installation

```

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:

bash go install go.abhg.dev/stitchmd@latest

For other installation methods, see the Installation section.

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

bash 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.

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

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

1. Run stitchmd on the summary.

bash stitchmd summary.md

The output should look similar to the following:

```markdown - Introduction - Features - 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.

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

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

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

```markdown - Introduction - Features - Installation

# Introduction

Welcome to my program. See 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:

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

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

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

• Add a heading to the summary.md:

```markdown # my awesome program

• Introduction
  • Features
• 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

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

• Automatically update your output file based on edits

```yaml 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

yaml 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



### Installation



## Usage



## API



# Appendix

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

## How things work



## FAQ

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


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



# 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

markdown - [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, a