DocumenterMarkdown.jl: Documenter's Markdown / MkDocs Backend

DocumenterMarkdown

This package provides a Markdown / MkDocs backend to Documenter.jl.

Package status: Currently, the package does not work with the 0.28 branch of Documenter, and therefore the latest versions of Documenter do not have a Markdown backend available. Older, released versions of this package can still be used together with older versions of Documenter (0.27 and earlier) to enable the Markdown backend built in to those versions of Documenter.

Right now, this package is not actively maintained. However, contributions are welcome by anyone who might be interested in using and developing this backend.

Installation

The package can be added using the Julia package manager. From the Julia REPL, type ] to enter the Pkg REPL mode and run

pkg> add DocumenterMarkdown

Usage

To enable the backend import the package in make.jl and then just pass format = Markdown() to makedocs:

using Documenter
using DocumenterMarkdown
makedocs(format = Markdown(), ...)

Documentation

DEVEL — documentation of the in-development version.

Download Details:

Author: JuliaDocs
Source Code: https://github.com/JuliaDocs/DocumenterMarkdown.jl
License: View license

#julia #markdown #docs

What is GEEK

Buddha Community

DocumenterMarkdown.jl: Documenter's Markdown / MkDocs Backend

hourly developer

1594888728

Hire Backend Developers India

Are you looking to hire experienced Backend Developers at a reasonable cost to boost-up your IT business?

Hire Backend Developers India and accomplish their business goals swiftly. Backend developers in HourlyDeveloper.io are well versed in writing complex functional protocols. They also have exceptional hands-on experience in using the latest technologies that give you custom, secure, and strong backend layers for your website and applications.

Consult with experts:- https://bit.ly/2WlYvA7

#hire backend developers india #backend developers #backend development company #backend development services #backend development #backend

hourly developer

1598859295

Hire Dedicated Backend Developers

Want to create a backend for a web or mobile app using PHP & JS frameworks?

Hire Dedicated Backend Developers who offer end-to-end, robust, scalable, and innovative website solutions. HourlyDeveloper.io technical analysts will also guide you on improving your web presence using their expertise. Also, we ensure your optimum level of freedom and control over your projects.

Let’s connect with our experts: https://bit.ly/2YLhmFZBackend Development Services

#hire dedicated backend developers #backend developers #backend development company #backend development services #backend development #backend

Julia Programming

1660275720

DocumenterMarkdown.jl: Documenter's Markdown / MkDocs Backend

DocumenterMarkdown

This package provides a Markdown / MkDocs backend to Documenter.jl.

Package status: Currently, the package does not work with the 0.28 branch of Documenter, and therefore the latest versions of Documenter do not have a Markdown backend available. Older, released versions of this package can still be used together with older versions of Documenter (0.27 and earlier) to enable the Markdown backend built in to those versions of Documenter.

Right now, this package is not actively maintained. However, contributions are welcome by anyone who might be interested in using and developing this backend.

Installation

The package can be added using the Julia package manager. From the Julia REPL, type ] to enter the Pkg REPL mode and run

pkg> add DocumenterMarkdown

Usage

To enable the backend import the package in make.jl and then just pass format = Markdown() to makedocs:

using Documenter
using DocumenterMarkdown
makedocs(format = Markdown(), ...)

Documentation

DEVEL — documentation of the in-development version.

Download Details:

Author: JuliaDocs
Source Code: https://github.com/JuliaDocs/DocumenterMarkdown.jl
License: View license

#julia #markdown #docs

Julia Programming

1660268100

Documenter.jl: A Documentation Generator for Julia

Documenter

A documentation generator for Julia.

Installation

The package can be installed with the Julia package manager. From the Julia REPL, type ] to enter the Pkg REPL mode and run:

pkg> add Documenter

Or, equivalently, via the Pkg API:

julia> import Pkg; Pkg.add("Documenter")

Documentation

STABLE — documentation of the most recently tagged version.
DEVEL — documentation of the in-development version.

Project Status

The package is tested against, and being developed for, Julia 1.6 and above on Linux, macOS, and Windows.

Questions and Contributions

Usage questions can be posted on the Julia Discourse forum under the documenter tag, in the #documentation channel of the Julia Slack and/or in the JuliaDocs Gitter chat room.

Contributions are very welcome, as are feature requests and suggestions. Please open an issue if you encounter any problems. The contributing page has a few guidelines that should be followed when opening pull requests and contributing code.

Related packages

There are several packages that extend Documenter in different ways. The JuliaDocs organization maintains:

Other third-party packages that can be combined with Documenter include:

Finally, there are also a few other packages in the Julia ecosystem that are similar to Documenter, but fill a slightly different niche:

Download Details:

Author: JuliaDocs
Source Code: https://github.com/JuliaDocs/Documenter.jl
License: MIT license

#julia #docs #document

Hermann Frami

1679956080

Stitch Multiple Markdown Files together into A Single Document

Stitchmd

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.

Flow diagram

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.

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.

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.

Create a summary file defining the layout between these files.

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

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.

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

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:

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)

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.

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

<!-- ... -->

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.

Download Details:

Author: Abhinav
Source Code: https://github.com/abhinav/stitchmd
License: MIT license

#markdown #go #golang #document