Markdown
Overview
Markdown is a simple format for authoring documentation. Static site generation frameworks such as mkdocs use markdown to simply the creation of websites.
Using LinkML you can go from a schema to a complete searchable website hosted on GitHub in minutes thanks to the markdown generator
See for example:
To run:
gen-markdown --index-file docs/schema.md -d docs personinfo.yaml
This will generate one markdown file per element, plus an index document.
Use with mkdocs
The markdown files can be ported across many frameworks. Currently, most projects that use linkml use mkdocs for site generation.
Using mkdocs you can set up a static site hosted on github in minutes. To get started:
Install mkdocs
Create a mkdocs.yml file
Run gen-markdown
After doing this, you can test the site locally:
mkdocs serve
Once you are finished you can make it live:
mkdocs gh-deploy
UML Class Diagrams
The markdown generator makes use of the yUML generator to place a UML diagram of the class locality at the head of each document.
Alternatives
A separate command is provided that uses a Jinja2 template based approach:
gen-docs -d docs personinfo.yaml
This is not yet as stable and feature complete as gen-markdown. One advantage is that it allows you to customize the templates used.
Docs
Command Line
gen-markdown
Generate markdown documentation of a LinkML model
gen-markdown [OPTIONS] YAMLFILE
Options
- -d, --dir <dir>
Required Output directory
- -c, --classes <classes>
Class(es) to emit
- -M, --map-fields <map_fields>
Map metamodel fields, e.g. slot=field
- -i, --img
Download YUML images to ‘image’ directory
- -I, --index-file <index_file>
Name of markdown file that holds index
- --noimages
Do not (re-)generate images
- --noyuml
Do not add yUML figures to pages
- --notypesdir
Do not create a separate types directory
- --warnonexist
Warn if output file already exists
- -f, --format <format>
Output format (default=md)
- Options
md
- --metadata, --no-metadata
Include metadata in output (default=–metadata)
- --useuris, --metauris
Include metadata in output (default=–useuris)
- -im, --importmap <importmap>
Import mapping file
- --log_level <log_level>
Logging level (default=WARNING)
- Options
CRITICAL | ERROR | WARNING | INFO | DEBUG
- --mergeimports, --no-mergeimports
Merge imports into source file (default=mergeimports)
Arguments
- YAMLFILE
Required argument
Code
- class linkml.generators.markdowngen.MarkdownGenerator(schema: Union[str, TextIO, linkml_runtime.linkml_model.meta.SchemaDefinition], no_types_dir: bool = False, noyuml: bool = False, warn_on_exist: bool = False, **kwargs)[source]
Generates markdown documentation for a LinkML schema
Each schema element (class, slot, type, enum) is translated into its own markdown file; additionally, an index.md is generated that links everything together.
The markdown is suitable for deployment as a MkDocs or Sphinx site
- serialize(**kwargs) str
Generate output in the required format
- Parameters
kwargs – Generater specific parameters
- Returns
Generated output