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:

  1. Install mkdocs

  2. Create a mkdocs.yml file

  3. 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

True

--useuris, --metauris

Include metadata in output

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

--mergeimports, --no-mergeimports

Merge imports into source file (default=mergeimports)

Arguments

YAMLFILE

Required argument

Code

class linkml.generators.markdowngen.MarkdownGenerator(schema: ~typing.Union[str, ~typing.TextIO, ~linkml_runtime.linkml_model.meta.SchemaDefinition, ~linkml.utils.generator.Generator], schemaview: ~typing.Optional[~linkml_runtime.utils.schemaview.SchemaView] = None, format: ~typing.Optional[str] = None, metadata: bool = <factory>, useuris: ~typing.Optional[bool] = None, log_level: int = 30, mergeimports: ~typing.Optional[bool] = <factory>, source_file_date: ~typing.Optional[str] = None, source_file_size: ~typing.Optional[int] = None, logger: ~typing.Optional[~logging.Logger] = None, verbose: ~typing.Optional[bool] = None, output: ~typing.Optional[str] = None, namespaces: ~typing.Optional[~linkml_runtime.utils.namespaces.Namespaces] = None, directory_output: bool = False, base_dir: ~typing.Optional[str] = None, metamodel_name_map: ~typing.Optional[~typing.Dict[str, str]] = None, importmap: ~typing.Optional[~typing.Union[str, ~typing.Mapping[str, str]]] = None, emit_prefixes: ~typing.Set[str] = <factory>, metamodel: ~typing.Optional[~linkml.utils.schemaloader.SchemaLoader] = None, directory: ~typing.Optional[str] = None, image_directory: ~typing.Optional[str] = None, classes: ~typing.Optional[~typing.Set[~linkml_runtime.linkml_model.meta.ClassDefinitionName]] = None, image_dir: bool = False, index_file: str = <factory>, noimages: bool = False, noyuml: bool = False, no_types_dir: bool = False, warn_on_exist: bool = False, gen_classes: ~typing.Optional[~typing.Set[~linkml_runtime.linkml_model.meta.ClassDefinitionName]] = None, gen_classes_neighborhood: ~typing.Optional[~linkml.utils.typereferences.References] = 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

serialize(**kwargs) str

Generate output in the required format

Parameters

kwargs – Generater specific parameters

Returns

Generated output