Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/abhinav/stitchmd
Stitch multiple Markdown files together into a single document.
https://github.com/abhinav/stitchmd
markdown
Last synced: 2 months ago
JSON representation
Stitch multiple Markdown files together into a single document.
- Host: GitHub
- URL: https://github.com/abhinav/stitchmd
- Owner: abhinav
- License: gpl-2.0
- Created: 2023-02-18T06:55:38.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-10-31T22:08:22.000Z (2 months ago)
- Last Synced: 2024-10-31T23:18:12.310Z (2 months ago)
- Topics: markdown
- Language: Go
- Homepage:
- Size: 616 KB
- Stars: 31
- Watchers: 2
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# stitchmd
- [Introduction](#introduction)
- [Getting Started](#getting-started)
- [Installation](#installation)
- [GitHub Action](#github-action)
- [Usage](#usage)
- [Options](#options)
- [Read from stdin](#read-from-stdin)
- [Add a preface](#add-a-preface)
- [Offset heading levels](#offset-heading-levels)
- [Disable the TOC](#disable-the-toc)
- [Write to file](#write-to-file)
- [Change the directory](#change-the-directory)
- [Report a diff](#report-a-diff)
- [Syntax](#syntax)
- [Advanced](#advanced)
- [Page Titles](#page-titles)
- [Absorbing headings](#absorbing-headings)
- [Including summaries](#including-summary-files)
- [License](#license)
## Introduction
[](https://github.com/abhinav/stitchmd/actions/workflows/ci.yml)
[](https://codecov.io/gh/abhinav/stitchmd)
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](#getting-started) for a tutorial,
or [Usage](#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
```
**Output**
```markdown
```
- **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](#usage).
1. First, [install stitchmd](#installation).
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](#installation) section.
2. 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](doc).
3. 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
```
4. Run stitchmd on the summary.
```bash
stitchmd summary.md
```
The output should look similar to the following:
```markdown
- [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:
```markdown
See [installation](install.md) for instructions.
```
If you run stitchmd now, the output should change slightly.
```markdown
- [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:
```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](#introduction)
- [Features](#features)
- [Installation](#installation)
```
### Installation
You can install stitchmd from [pre-built binaries](#binary-installation)
or [from source](#install-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:
```bash
brew install abhinav/tap/stitchmd
```
##### ArchLinux
If you use **ArchLinux**,
install stitchmd from [AUR](https://aur.archlinux.org/)
using the [stitchmd-bin](https://aur.archlinux.org/packages/stitchmd-bin/)
package.
```bash
git clone https://aur.archlinux.org/stitchmd-bin.git
cd stitchmd-bin
makepkg -si
```
If you use an AUR helper like [yay](https://github.com/Jguer/yay),
run the following command instead:
```go
yay -S stitchmd-bin
```
##### GitHub Releases
For **other platforms**, download a pre-built binary from the
[Releases page](https://github.com/abhinav/stitchmd/releases)
and place it on your `$PATH`.
#### Install from source
To install stitchmd from source, [install Go >= 1.20](https://go.dev/dl/)
and run:
```bash
go install go.abhg.dev/stitchmd@latest
```
### GitHub Action
[stitchmd-action](https://github.com/abhinav/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](https://github.com/abhinav/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:
```markdown
# 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](#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:
```markdown
# 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`](#add-a-preface)
- [`-offset N`](#offset-heading-levels)
- [`-no-toc`](#disable-the-toc)
- [`-o FILE`](#write-to-file)
- [`-C DIR`](#change-the-directory)
- [`-d`](#report-a-diff)
#### 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.
```bash
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:
```bash
cat > generated.txt <
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**
```markdown
# User Guide
- [Introduction](intro.md)
- [Installation](install.md)
```
```bash
stitchmd -offset 1 summary.md
```
**Output**
```markdown
## User Guide
- [Introduction](#introduction)
- [Installation](#installation)
### Introduction
### Installation
```
Use a negative value to reduce heading levels.
Example
**Input**
```markdown
# User Guide
- [Introduction](intro.md)
- [Installation](install.md)
```
```bash
stitchmd -offset -1 summary.md
```
**Output**
```markdown
# 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.
```bash
stitchmd -no-toc summary.md
```
This will omit the item listing under each section.
Example
**Input**
```markdown
- [Introduction](intro.md)
- [Installation](install.md)
```
```bash
stitchmd -no-toc summary.md
```
**Output**
```markdown
# 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.
```bash
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.
```bash
stitchmd -C docs summary.md
```
This is especially useful if your summary file is
[passed via stdin](#read-from-stdin)
```bash
... | stitchmd -C docs -
```
#### Report a diff
```
-d
```
stitchmd normally writes output directly to the file
if you pass in a filename with [`-o`](#write-to-file).
Use the `-d` flag to instead have it report what would change
in the output file without actually changing it.
```bash
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
```markdown
# 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 ``.
The included file will be read as another summary file,
and its sections will nested under this heading.
Example
```markdown
- 
```
- **Plain text**:
These will become standalone headers in the output.
These **must** have a nested list.
Example
```markdown
- 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
```markdown
- [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**
```markdown
# 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**
```markdown
# 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**
```markdown
## User Guide
- [Introduction](intro.md)
```
**Output**
```markdown
## 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:
```markdown
- [Introduction](intro.md)
Welcome to Foo.
```
The title for `intro.md` is `"Introduction"`.
Output
```markdown
- [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:
```markdown
- [Introduction](intro.md)
# Introduction to Foo
Welcome to Foo.
```
The title for `intro.md` will be `"Introduction to Foo"`.
Output
```markdown
- [Introduction](#introduction-to-foo)
# Introduction to Foo
Welcome to Foo.
```
### Absorbing headings
When adding another Markdown file to your summary,
you can pull the headings of the included file in the final output
by adding a YAML front matter block to the top of the file.
```yaml
---
absorb: true
---
```
For example, given the following:
```markdown
- [Installation](install.md)
- [Configuration](config.md)
---
absorb: true
---
# Configuration
## Adding a new user
To add a new user, ...
## Removing a user
To remove a user, ...
```
Output
```markdown
- [Installation](#install)
- [Configuration](#configuration)
- [Adding a new user](#adding-a-new-user)
- [Removing a user](#removing-a-user)
# Installation
# Configuration
## Adding a new user
To add a new user, ...
## Removing a user
To remove a user, ...
```
### Including summary files
List items in the following form are requests to include another summary file:
```markdown
- 
```
The list defined in the included summary file will be nested under this item.
For example, given the following:
```markdown
- [Installation](install.md)
- [Configuration](config.md)
- [Dashboard](dashboard.md)
- [Troubleshooting](troubleshooting.md)
```
A joint summary file could take the form:
```markdown
- 
- 
```
Output
```markdown
- [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.
```