options.md

absorb
true

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.