Markdown#
Overview#
Markdown is a lightweight markup language with simple, readable syntax that can be used to author technical documentation pages.
Some static site/documentation generator frameworks (such as mkdocs) use markdown to simplify the creation of websites.
The LinkML framework has a utility called gen-doc which can be
used to automatically create documentation pages from your hand authored schema.
Above is a schematic diagram explaining the working mechanism of the gen-doc module.
The documentation generation module takes in the path to your schema directory as an argument.
It also ships with some base jinja2 templates for each schema element which controls the content
rendered on documentation pages for that schema elements.
For example, there is a jinja2 template for classes, one for slots, etc. Optionally linkml also
allows you to exercise more granular control on the content rendered on pages, by allowing you to
customize the jinja2 templates based on your requirement.
gen-doc turns your YAML schemas into Markdown documentation pages.
It also has utilities that allow you to further convert those Markdown pages into HTML pages (using mkdocs)
that can be hosted on website hosting services like GitHub Pages.
Examples of sites that have been auto generated by linkml gen-doc and hosted on gh-pages:
To generate documentation pages for your schema, run:
gen-doc ~/path/to/schema.yaml
The documentation generator will generate one Markdown file per element, along with an index document. Some other important options that can be configured while running the generator:
--template-directory: path to the directory with custom jinja2 templates--directory: path to directory where you want the markdown files to be written to--hierarchical-class-view / --no-hierarchical-class-view: control style of rendering classes on index page
gen-doc renders Mermaid UML class diagrams
by default on individual class documentation pages to summarize it’s relationship with other
classes and slots.
Note:
We have two Markdown documentation generators within the linkml framework - gen-doc and gen-markdown.
It is important to note that while gen-markdown still works, it has been deprecated (no active development)
in favour of the de facto gen-doc generator.
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
- -V, --version#
Show the version and exit.
- -f, --format <format>#
Output format
- Default:
'md'- Options:
md
- --metadata, --no-metadata#
Include metadata in output
- Default:
True
- --useuris, --metauris#
Use class and slot URIs over model uris
- Default:
True
- -im, --importmap <importmap>#
Import mapping file
- --log_level <log_level>#
Logging level
- Default:
'WARNING'- Options:
CRITICAL | ERROR | WARNING | INFO | DEBUG
- -v, --verbose#
Verbosity. Takes precedence over –log_level.
- --mergeimports, --no-mergeimports#
Merge imports into source file (default=mergeimports)
- --stacktrace, --no-stacktrace#
Print a stack trace when an error occurs
- Default:
False
Arguments
- YAMLFILE#
Required argument
Code#
- class linkml.generators.markdowngen.MarkdownGenerator(schema: str | ~typing.TextIO | ~linkml_runtime.linkml_model.meta.SchemaDefinition | ~linkml.utils.generator.Generator | ~pathlib.Path, schemaview: ~linkml_runtime.utils.schemaview.SchemaView | None = None, format: str | None = None, metadata: bool = True, useuris: bool | None = None, log_level: int | None = 30, mergeimports: bool | None = True, source_file_date: str | None = None, source_file_size: int | None = None, logger: ~logging.Logger | None = None, verbose: bool | None = None, output: str | None = None, namespaces: ~linkml_runtime.utils.namespaces.Namespaces | None = None, directory_output: bool = False, base_dir: str = None, metamodel_name_map: ~typing.Dict[str, str] = None, importmap: str | ~typing.Mapping[str, str] | None = None, emit_prefixes: ~typing.Set[str] = <factory>, metamodel: ~linkml.utils.schemaloader.SchemaLoader = None, stacktrace: bool = False, include: str | ~pathlib.Path | ~linkml_runtime.linkml_model.meta.SchemaDefinition | None = None, directory: str | None = None, image_directory: str | None = None, classes: ~typing.Set[~linkml_runtime.linkml_model.meta.ClassDefinitionName] = None, image_dir: bool = False, index_file: str = 'index.md', noimages: bool = False, noyuml: bool = False, no_types_dir: bool = False, warn_on_exist: bool = False, gen_classes: ~typing.Set[~linkml_runtime.linkml_model.meta.ClassDefinitionName] | None = None, gen_classes_neighborhood: ~linkml.utils.typereferences.References | None = None, **_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