https://github.com/oxy2dev/markdoc
A very simple "markdown" to "vimdoc" converter.
https://github.com/oxy2dev/markdoc
Last synced: about 1 year ago
JSON representation
A very simple "markdown" to "vimdoc" converter.
- Host: GitHub
- URL: https://github.com/oxy2dev/markdoc
- Owner: OXY2DEV
- License: mit
- Created: 2024-12-07T01:48:25.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-19T13:51:45.000Z (about 1 year ago)
- Last Synced: 2025-04-19T18:06:44.776Z (about 1 year ago)
- Language: Lua
- Size: 581 KB
- Stars: 16
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
✨ markdoc
A feature rich markdown to vimdoc converter for pandoc.
## 🥅 Goals
| Goal | Progress |
|------------------------------------------|----------|
| Basic markdown syntax support | Complete |
| Basic HTML support | Complete |
| Handling of `\n` in HTML | Complete |
| Allowing text alignment | Complete |
| Callout support | Complete |
| Wrap for nested elements | Complete |
| Ability to change configuration per file | Complete |
| Ability to place TOC anywhere | Complete |
| Handling LaTeX | None |
| Handling characters with varying widths | None |
| More syntax support(HTML, Markdown) | None |
## 💥 Features
- Config per file, allows configuring `markdoc` using YAML metadata.
- Tag(s) per heading, allows using Lua patterns to add one or more tags to matching headings.
- Creating TOCs, allows creating Table of contents via YAML.
- Callout & title support, supports callouts(even custom ones) and titles for block quotes.
- Prettier table rendering, tables can be created with custom borders with text wrapping support.
- Nesting support, supports nesting of block elements.
- Base HTML support, supports basic HTML tags.
- `align=""` support, allows aligning text via HTML.
## 📚 Usage
You only need the `markdoc.lua` file. So, just copy it to your desired location.
You can then run it like so,
```shell
pandoc -t path/to/markdoc.lua README.md -o help.txt
```
>[!TIP]
> You can store metadata in a separate file too if you like. Then you will do something like this,
>
> ```sh
> # Load the metadata file first
> pandoc metadata.md README.md -t path/to/markdoc.lua -o help.txt
> ```
## 💨 Github actions
>[!WARNING]
> I am not very knowledgable when it comes to GitHub actions, so feel free to do PR(s) to fix issues I missed.
```yml
name: markdoc
on:
push:
branches:
- main
permissions:
contents: write
jobs:
doc:
runs-on: ubuntu-latest
name: "To vimdoc"
steps:
- uses: actions/checkout@v2
with:
ref: ${{ github.heade_ref }}
- uses: OXY2DEV/markdoc@main
with:
config: '{ "doc/markdoc.txt": [ "mREADME.md", "README.md" ] }'
help_dirs: '[ "doc" ]'
- uses: stefanzweifel/git-auto-commit-action@v5
with:
commit_message: "doc: Generated help files"
branch: ${{ github.head_ref }}
```
This basically runs `git checkout`, `pandoc mREADME.md README.md -t markdoc.lua -o doc/markdoc.txt`, `git add .` and `git commit -m "doc: Generated help files"`.
### 📌 Configuring workflow
The workflow comes with a single option, `config`. It's a JSON string that actually looks like this,
```json
{
"doc/markdoc.txt": [ "mREADME.md", "README.md" ]
}
```
This generates `markdoc.txt` from `mREADME.md`(this file is used for metadata) and `README.md`.
You can add more keys to create more files. For example,
```json
{
"doc/markdoc.txt": [ "mREADME.md", "README.md" ],
"doc/markdoc-arch.txt": [ "ARCHITECTURE.md" ]
}
```
This will generate another help file named `markdoc-arch` from the `ARCHITECTURE.md` file.
---
As of `v3` there is also a `help_dirs` option. This is a JSON list of directories where `helptags` will be run.
```json
[ "doc" ]
```
By default it only runs on the `doc/` directory.
## 🪨 Limitations
>[!IMPORTANT]
> `markdoc` is best-effort only. It's not perfect but for most use cases it should be good enough.
- Whitespace loss, due to the nature of syntax trees the whitespace in the document may not be preserved.
- Issues with complex characters, some UTF-8 characters don't get properly wrapped(either due to multi-byte width or limitation of Lua).
- Issues with complex document structures, though `markdoc` should support complex documents it is still preferable to keep them simple.
You may encounter text wrapping issues if the document gets too deeply nested(due to lack of space).
## 🔩 Configuration
"One function to rule them all,
One function to find them,
One function to bring them all,
And in the darkness bind them."
You can configure `markdoc` for a file by adding a YAML metadata section to the start of the file.
It should look something like this,
```text
---
markdoc:
textwidth: 78
title: "Markdown 🤝 Vimdoc"
title_tag: "markdoc"
tags:
Features$: [ "markdoc-features", "markdoc-feat" ]
Usage$: [ "markdoc-usage" ]
---
Some text.
```
>[!NOTE]
> All configuration options should be inside `markdoc`.
The configuration options are given below,
### block_quotes
Changes block quote configuration.
#### Example
```yaml
block_quotes:
default:
border: "║"
# Name SHOULD be in lowercase.
# This will match any variation of,
# [!CUSTOM]
custom:
border: "┊" # Block quote border
callout: "🎵 Custom" # Text to show at the top
icon: "🎵" # Icon before title(if there is any).
```
### fold_refs
When `true`, link & image references are folded.
#### Example
```yaml
fold_refs: true
```
### foldmarkers
Markers used for folding.
#### Example
```yaml
# This is the same as `:set foldmarker`
foldmarkers: "{{{,}}}"
```
### tags
Tag configuration for different headings.
#### Example
```yaml
tags:
# The key is a Lua patter.
Features$: [ "markdoc-features", "markdoc-feat" ] # Adds 2 tags to headings ending with Feature.
Usage$: [ "markdoc-usage" ]
```
### table
Table configuration.
#### Example
```yaml
table:
col_minwidth: 10 # Minimum width for columns.
top: [ "╭", "─", "╮", "┬" ]
header: [ "│", "│", "│" ]
separator: [ "├", "─", "┤", "┼" ]
header_separator: [ "├", "─", "┤", "┼" ]
row_separator: [ "├", "─", "┤", "┼" ]
row: [ "│", "│", "│" ]
bottom: [ "╰", "─", "╯", "┴" ]
```
### textwidth
Width of the document.
#### Example
```yaml
# Same as `:set textwidth`
textwidth: 78
```
### title
Title of the document.
#### Example
```yaml
title: "Markdown 🤝 Vimdoc"
```
### title_tag
Tag for the document title.
#### Example
```yaml
title_tag: "markdoc"
```
### toc_title
Title for the generated table of contents section.
Defaults to `Table of contents:` when unset.
#### Example
```yaml
toc_title: "Markdoc: TOC"
```
### toc
Entries for the table of contents.
>[!TIP]
> You can add `` to anywhere in your document and the table of contents will be placed there!
> However, It will also only replace the 1st one.
#### Example
```yaml
toc:
"Features": "markdoc-features"
```
------
Vimdoc version, see `doc/markdoc.txt`.
Markdown version, see `README.md`(metadata is at `mREADME.md`).