• Introduction
  • Getting Started
  • Installation
• Usage
  • Options
  • Syntax
  • Page Titles
• License

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.

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

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

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)

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

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

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

brew install abhinav/tap/stitchmd

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

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

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

go install go.abhg.dev/stitchmd@latest

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.

# 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 -->

stitchmd supports the following options:

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

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 -

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

# User Guide

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

stitchmd -offset 1 summary.md

## User Guide

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

### Introduction

<!-- ... -->

### Installation

<!-- ... -->

Use a negative value to reduce heading levels.

# User Guide

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

stitchmd -offset -1 summary.md

# User Guide

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

# Introduction

<!-- ... -->

## Installation

<!-- ... -->

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

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

stitchmd -no-toc summary.md

# Introduction

<!-- .. -->

# Installation

<!-- .. -->

-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

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

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

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.

# 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)

• 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)

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.

# Section 1

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

# Section 2

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

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

## User Guide

- [Introduction](intro.md)

## User Guide

- [Introduction](#introduction)

### Introduction

<!-- ... -->

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

- [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".

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

# Introduction to Foo

Welcome to Foo.

This software is made available under the MIT license.