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-doc -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

-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#

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)

--stacktrace, --no-stacktrace#

Print a stack trace when an error occurs

Default:

False

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, stacktrace: bool = False, 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