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.

../_images/documentation_generation_schematic.png

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#

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 – Generator specific parameters

Returns:

Generated output