Document Reference

Doorstop documents are folders, with metadata stored in a configuration YAML file .doorstop.yml directly below the folder.

Standard Document Attributes

Upon creation, .doorstop.yml contains default settings.

$ doorstop create REQ ./reqs
created document: REQ (@/reqs)

Then open REQ/.doorstop.yml in any text editor:

settings:
  digits: 3
  prefix: REQ
  sep: ''

settings

Parameters that affect the entire document fall under here.

digits

Defines the number of digits in an item UID. The default value is 3. Optionally, you can set it through the -d command line option of the doorstop create command. It is a mandatory and read-only document setting.

parent

Defines the parent document prefix. You set it through the -p command line option of the doorstop create command. It is an optional and read-only document setting.

prefix

Defines the document prefix. You set it through the prefix of the doorstop create command. It is a mandatory and read-only document setting.

sep

Defines the separator between the document prefix and the number in an item UID. The default value is the empty string. You have to set it manually before an item is created. Afterwards, it should be considered as read-only. This document setting is mandatory.

Extended Document Attributes

In addition to the standard attributes, Doorstop will allow any number of custom extended attributes (key-value pairs) in the YAML file. The extended attributes will not be part of a published document, but they can be queried by a 3rd party application through the REST interface or the Python API.

attributes

Extended document attributes fall under here.

defaults

Defines the defaults for extended attributes. This is an optional document configuration option.

reviewed

Defines which extended attributes contribute to the item fingerprint. This is an optional document configuration option.

In the document configuration files, you can include other YAML files through a value tagged with !include. The path to the included file is always relative to the directory of the file with the include tag. Absolute paths are not supported. Please have a look at this example:

In .doorstop.yml:

settings:
  digits: 3
  prefix: REQ
  sep: ''
attributes:
  defaults:
    text: !include path/to/file.yml

In path/to/file.yml:

|
  Some template text, which may
  have several
  lines.