Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mseri/md2mld
Little cli to convert md files into mld files
https://github.com/mseri/md2mld
hacktoberfest mld odoc
Last synced: about 2 months ago
JSON representation
Little cli to convert md files into mld files
- Host: GitHub
- URL: https://github.com/mseri/md2mld
- Owner: mseri
- License: isc
- Created: 2018-06-15T10:49:53.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2023-05-01T13:48:29.000Z (over 1 year ago)
- Last Synced: 2024-10-13T21:30:07.207Z (2 months ago)
- Topics: hacktoberfest, mld, odoc
- Language: OCaml
- Homepage:
- Size: 425 KB
- Stars: 27
- Watchers: 5
- Forks: 3
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGES.md
- License: LICENSE
Awesome Lists containing this project
- awesome-list - md2mld
README
# md2mld: Convert md files into odoc mld files
`md2mld` converts a Markdown-format file into the `mld` format used by [odoc](https://github.com/ocaml/odoc) to render HTML documentation or OCaml libraries. You can use this script to automatically embed a `README.md` file into API documentation for an OCaml library.
## Usage
You can use it manually as follows
```console
$ md2mld filename.md > outfile.mld
```
In `dune` you can use it to generate an mld file with
```text
(rule
(target outfile.mld)
(deps filename.md)
(action
(with-stdout-to outfile.mld (run md2mld filename.md))))
```
Attach the mld file using the [`(documentation …)` stanza](https://dune.readthedocs.io/en/stable/documentation.html#documentation-stanza-examples).
You can see the documentation generated from the latest tagged version of this README at [mseri.github.io/md2mld/md2mld](https://mseri.github.io/md2mld/md2mld).
## Known issues
- Until the new odoc [fixing #141](https://github.com/ocaml/odoc/issues/141) is released, the minimal header allowed in the `md` file will be the level 3 one `###`.
You can work around this by using the `-min-header 3` flag during the invocation of `md2mld`.
- If you see an error like `'{0': heading level should be lower than top heading level '0'`, this is because in `ocamldoc` the first header must have a level higher than all other headings in the page.
You can safely ignore it or increase the level of the subsequent headings to get rid of it.