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