Debug¶
This page shows raw data as passed to the markdown parser:
target¶
{'hover_anchors': '¶', 'skip_cover': True, 'name': 'everything', 'display_name': 'Dactyl: A Heroic Doc Tool', 'filters': ['demote_headers'], 'demote_headers_pdf_only': True, 'stylesheet': 'template_assets/dactyl.css', 'foo': 'fooooooo'}
pages¶
[{'blurb': 'Documentation tools for enterprise-quality documentation from '
'Markdown source. Dactyl has advanced features to enable '
'single-sourcing and an extensible syntax for building '
'well-organized, visually attractive docs. It generates output in '
'HTML (natively), and can make PDFs if you have Prince installed.',
'children': [{'__dactyl_provided_filename__': True,
'blurb': 'Dactyl is intended to be used with a config file '
'(typically dactyl-config.yml) that specifies a full '
'list of files to build with necessary metadata and '
"other config. So, if you've got this set up, you can "
'run Dactyl like this:',
'children': [{'__dactyl_provided_filename__': True,
'blurb': 'Dactyl is intended to be used with a '
'config file containing a list of pages '
'to parse. Pages are grouped into '
'"targets" that represent a group of '
'documents to be built together; a page '
'can belong to multiple targets, and '
'can even contain conditional syntax so '
'that it builds differently depending '
'on the target in question. Targets and '
'pages can also use different templates '
'from each other, and pages can inherit '
'semi-arbitrary key/value pairs from '
'the targets.',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Configuration¶': '#configuration',
'Directory Paths¶': '#directory-paths',
'Pages¶': '#pages',
'Targets¶': '#targets'},
'hover_anchors': '¶',
'html': 'config.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d336dc0>,
'md': 'usage/config.md',
'name': 'Configuration',
'parent': 'usage.html',
'plaintext': 'Configuration¶\n'
'Dactyl is intended to be used with '
'a config file containing a list of '
'pages to parse. Pages are grouped '
'into "targets" that represent a '
'group of documents to be built '
'together; a page can belong to '
'multiple targets, and can even '
'contain conditional syntax so that '
'it builds differently depending on '
'the target in question. Targets '
'and pages can also use different '
'templates from each other, and '
'pages can inherit semi-arbitrary '
'key/value pairs from the targets.\n'
'The input pages in the config file '
'should be specified relative to '
'the content_path, which is '
'content/ by default. You can also '
'specify a URL to pull in a '
'Markdown file from a remote '
'source, but if you do, Dactyl '
"won't run any pre-processing on "
'it.\n'
'Directory Paths¶\n'
'An advanced setup would probably '
'have a directory structure such as '
'the following:\n'
'./ # '
'Top-level dir; this is where you '
'run dactyl_*\n'
'./dactyl-config.yml # Default '
'config file name\n'
'./content # Dir '
'containing your .md source files\n'
'---------/*/*.md # You can '
'sort .md files into subdirs if you '
'like\n'
'---------/static/* # Static '
'images referencd in your .md '
'files\n'
'./templates/template-*.html # '
'Custom HTML Templates\n'
'./assets # '
'Directory for static files '
'referenced by templates\n'
'./out # '
'Directory where output gets '
'generated. Can be deleted\n'
'\n'
'All of these paths can be '
'configured.\n'
'Targets¶\n'
'A target represents a group of '
'pages, which can be built together '
'or concatenated into a single PDF. '
'You should have at least one '
'target defined in the targets '
'array of your Dactyl config file. '
'A target definition should consist '
'of a short name (used to specify '
'the target in the commandline and '
'elsewhere in the config file) and '
'a human-readable display_name '
'(used mostly by templates but also '
'when listing targets on the '
'commandline).\n'
'A simple target definition:\n'
'targets:\n'
' - name: kc-rt-faq\n'
' display_name: Ripple Trade '
'Migration FAQ\n'
'\n'
'In addition to name and '
'display_name, a target definition '
'can contain arbitrary key-values '
'to be inherited by all pages in '
'this target. Dictionary values are '
'inherited such that keys that '
"aren't set in the page are carried "
'over from the target, recursively. '
'The rest of the time, fields that '
'appear in a page definition take '
'precedence over fields that appear '
'in a target definition.\n'
'Some things you may want to set at '
'the target level include filters '
'(an array of filters to apply to '
'pages in this target), template '
'(template to use when building '
'HTML), and pdf_template (template '
'to use when building PDF). You can '
'also use the custom values in '
'templates and preprocessing. Some '
'filters define additional fields '
"that affect the filter's "
'behavior.\n'
'The following field names cannot '
'be inherited: name, display_name, '
'and pages.\n'
'Pages¶\n'
'Each page represents one HTML file '
'in your output. A page can belong '
'to one or more targets. When '
'building a target, all the pages '
'belonging to that target are built '
'in the order they appear in the '
'pages array of your Dactyl config '
'file.\n'
'Example of a pages definition with '
'two files:\n'
'pages:\n'
' - name: RippleAPI\n'
' category: References\n'
' html: '
'reference-rippleapi.html\n'
' md: '
'https://raw.githubusercontent.com/ripple/ripple-lib/0.17.2/docs/index.md\n'
' filters:\n'
' - remove_doctoc\n'
' - add_version\n'
' targets:\n'
' - local\n'
' - ripple.com\n'
'\n'
' - name: rippled\n'
' category: References\n'
' html: '
'reference-rippled.html\n'
' md: reference-rippled.md\n'
' targets:\n'
' - local\n'
' - ripple.com\n'
'\n'
'Each individual page definition '
'can have the following fields:\n'
'\n'
'\n'
'\n'
'Field\n'
'Type\n'
'Description\n'
'\n'
'\n'
'\n'
'\n'
'targets\n'
'Array\n'
'The short names of the targets '
'that should include this page.\n'
'\n'
'\n'
'html\n'
'String\n'
'(Optional) The filename where this '
'file should be written in the '
'output directory. If omitted, '
'Dactyl chooses a filename based on '
'the md field (if provided), the '
'name field (if provided), or the '
'current time (as a last resort). '
'By default, generated filenames '
'flatten the folder structure of '
'the md files. To instead replicate '
'the folder structure of the source '
'documents in auto-generated '
'filenames, add '
'flatten_default_html_paths: true '
'to the top level of your Dactyl '
'config file.\n'
'\n'
'\n'
'name\n'
'String\n'
'(Optional) Human-readable display '
'name for this page. If omitted but '
'md is provided, Dactyl tries to '
'guess the right file name by '
'looking at the first two lines of '
'the md source file.\n'
'\n'
'\n'
'md\n'
'String\n'
'(Optional) The markdown filename '
'to parse to generate this page, '
'relative to the content_path in '
'your config. If this is not '
'provided, the source file is '
'assumed to be empty. (You might do '
'that if you use a nonstandard '
'template for this page.)\n'
'\n'
'\n'
'openapi_specification\n'
'String\n'
'(Optional) The file path or '
'http(s) URL to an OpenAPI v3.0 '
'specification to be parsed into '
'generated documentation. If '
'provided, this entry becomes '
'expanded into a set of several '
'pages that describe the methods '
'and data types defined for the '
'given API. The generated pages '
'inherit the other fields of this '
'page object. Experimental. If the '
'path is a relative path, it is '
'evaluated based on the directory '
'Dactyl is called from, not the '
'content directory.\n'
'\n'
'\n'
'api_slug\n'
'String\n'
'(Optional) If this is an '
'openapi_specification entry,\n'
'\n'
'\n'
'category\n'
'String\n'
'(Optional) The name of a category '
'to group this page into. This is '
"used by Dactyl's built-in "
'templates to organize the table of '
'contents.\n'
'\n'
'\n'
'template\n'
'String\n'
'(Optional) The filename of a '
'custom Jinja HTML template to use '
'when building this page for HTML, '
'relative to the template_path in '
'your config.\n'
'\n'
'\n'
'pdf_template\n'
'String\n'
'(Optional) The filename of a '
'custom Jinja HTML template to use '
'when building this page for PDF, '
'relative to the template_path in '
'your config.\n'
'\n'
'\n'
'openapi_md_template_path\n'
'String\n'
'(Optional) Path to a folder '
'containing templates to be used '
'for OpenAPI spec parsing. If '
'omitted, use the built-in '
'templates.\n'
'\n'
'\n'
'parent\n'
'String\n'
'(Optional) The HTML filename of '
'the page to treat as a parent of '
'this one for purposes of '
'hierarchy. If omitted, treat the '
'page as a "top-level" page.\n'
'\n'
'\n'
'...\n'
'(Various)\n'
'Additional arbitrary key-value '
'pairs as desired. These values can '
'be used by templates or '
'pre-processing.\n'
'\n'
'\n'
'\n'
'If the file specified by md begins '
'with YAML frontmatter, separated '
'by a line of exactly ---, the '
'frontmatter is used as a basis for '
'these fields. Certain frontmatter '
'fields are adapted from Jekyll '
'format to Dactyl format: for '
'example, title gets copied to name '
'if the page does not have a name.\n'
'The following fields are '
'automatically added after a page '
"has been parsed to HTML. (They're "
'not available when preprocessing '
'or rendering Markdown to HTML, but '
'are available when rendering HTML '
'templates.)\n'
'\n'
'\n'
'\n'
'Field\n'
'Type\n'
'Description\n'
'\n'
'\n'
'\n'
'\n'
'plaintext\n'
'String\n'
'A plaintext-only version of the '
"page's markdown content, with all "
'Markdown and HTML syntax removed.\n'
'\n'
'\n'
'headermap\n'
'Dictionary\n'
"A mapping of the page's headers to "
'the unique IDs of those headers in '
'the generated HTML version.\n'
'\n'
'\n'
'blurb\n'
'String\n'
'An introductory blurb generated '
"from the page's first paragraph of "
'text.\n'
'\n'
'\n'
'children\n'
'List\n'
'A list of pages, in order of '
'appearance, that refer to this '
'page as their parent. Each of '
'these "child" pages is a reference '
'to the page definition '
'(dictionary) for that child.\n'
'\n'
'\n'
'is_ancestor_of\n'
'Function\n'
'A function that takes one '
'argument, the string identifying a '
'potential child page by that '
"child's html field. This function "
'returns True if this page is a '
'direct or indirect parent of the '
'child page.\n'
'\n'
'\n',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'__dactyl_provided_filename__': True,
'blurb': 'Dactyl includes a link-checking script '
'to automatically detect and report on '
'broken hyperlinks in your generated '
'documentation.',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Link Checking¶': '#link-checking',
'Unusual Link Types¶': '#unusual-link-types',
'Usage¶': '#usage'},
'hover_anchors': '¶',
'html': 'link-checking.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d336e50>,
'md': 'usage/link-checking.md',
'name': 'Link Checking',
'parent': 'usage.html',
'plaintext': 'Link Checking¶\n'
'Dactyl includes a link-checking '
'script to automatically detect and '
'report on broken hyperlinks in '
'your generated documentation.\n'
'Usage¶\n'
'First, build some documentation to '
'an output path. Depending on your '
'configuration, you may want to '
'build multiple targets to '
'different output directories '
'before running the link checker.\n'
'Then, run the link checker as '
'follows:\n'
'$ dactyl_link_checker\n'
'\n'
'This checks all the files in the '
'output directory for links and '
'confirms that any HTTP(S) links, '
'including relative links to other '
'files, are valid. For anchor '
'links, it checks that an element '
'with the correct ID exists in the '
'target file. It also checks that '
'the src of all image tags exists.\n'
'If there are links that are always '
"reported as broken but you don't "
'want to remove (for example, URLs '
"that block Python's user-agent) "
'you can add them to the '
'known_broken_links array in the '
'config.\n'
'In quiet mode (-q), the link '
'checker still reports in every 30 '
"seconds just so that it doesn't "
'get treated as stalled and killed '
'by continuous integration software '
'(e.g. Jenkins).\n'
'To reduce the number of '
'meaningless failure reports '
'(because a particular website '
'happened to be down momentarily '
'while you ran the link checker), '
'if there are any broken remote '
'links, the link checker waits 2 '
'minutes after finishing and then '
'retries those links in case they '
'came back up. (If they did, '
"they're not considered broken for "
"the link checker's final report.)\n"
'You can also run the link checker '
'in offline mode (-o) to skip any '
'remote links and just check that '
'the files and anchors referenced '
'exist in the output directory.\n'
'If you have a page that uses '
'JavaScript or something to '
'generate anchors dynamically, the '
"link checker can't find those "
"anchors (since it doesn't run any "
'JS). You can add such pages to the '
'ignore_anchors_in array in your '
'config to skip checking for links '
'that go to anchors in such pages.\n'
'Unusual Link Types¶\n'
'Some unusual types of links that '
'you may encounter in HTML or '
'Markdown include:\n'
'\n'
'Protocol relative URL - these '
'start with // and refer to '
'"whatever protocl is being used '
'now". Dactyl assumes HTTPS should '
'work for these URLs.\n'
'Mailto URL - Email addresses. The '
'link checker ignores these and '
'other links that use other URI '
'schemes.\n'
'Javascript Bookmarklet - '
'JavaScript code embedded in the '
'href directly with javascript:. '
'The link checker ignores these.\n'
'Empty anchor - A link to #. This '
'type of link is often used to '
'trigger JavaScript events. The '
'link checker considers these '
'invalid for <img> paths but OK for '
'<a> tags.\n',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'__dactyl_provided_filename__': True,
'blurb': 'The style checker is experimental. It '
'is only suitable for English text. It '
'reports several details about document '
'contents that may be helpful for '
'identifying documents whose '
'readability you could improve. These '
'details are:',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Discouraged Words and Phrases¶': '#discouraged-words-and-phrases',
'Length Metrics¶': '#length-metrics',
'Readability Goals¶': '#readability-goals',
'Readability Scores¶': '#readability-scores',
'Spell Checking¶': '#spell-checking',
'Style Checking¶': '#style-checking'},
'hover_anchors': '¶',
'html': 'style-checking.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d336ee0>,
'md': 'usage/style-checking.md',
'name': 'Style Checking',
'parent': 'usage.html',
'plaintext': 'Style Checking¶\n'
'The style checker is experimental. '
'It is only suitable for English '
'text. It reports several details '
'about document contents that may '
'be helpful for identifying '
'documents whose readability you '
'could improve. These details are:\n'
'\n'
'Discouraged words and phrases.\n'
'Page length details.\n'
'Readability scores.\n'
'Spell-checking.\n'
'\n'
'Example usage:\n'
'$ dactyl_style_checker\n'
'\n'
'The style checker re-generates '
'contents in-memory (never writing '
'it out), unlike the link checker '
'which requires you to run '
'dactyl_build first. It only checks '
'contents that come from Markdown, '
'not from HTML templates.\n'
'The style checker uses the first '
'target in the config file unless '
'you specify another target with '
'-t. You can check just one file by '
'passing its HTML path in the '
'--only parameter.\n'
'The exit code of the command is 0 '
'(success) if it found no '
'discouraged words, the spell '
'checker found no unknown words, '
'and no pages failed their '
'configured readability goals. '
'Otherwise, the exit code of the '
'command is 1 (failure).\n'
'Discouraged Words and Phrases¶\n'
'You can suggest specific words or '
'phrases to discourage. The style '
'checker checks for instances of '
'these words and phrases in '
"documents' content, and suggests "
'alternatives based on the phrase '
'file. Dactyl does not check text '
'in <code>, <pre>, and <tt> '
'elements since those are intended '
'to be code samples.\n'
'To configure lists of discouraged '
'words and phrases, add the '
'following config options:\n'
'\n'
'\n'
'\n'
'Field\n'
'Value\n'
'Description\n'
'\n'
'\n'
'\n'
'\n'
'word_substitutions_file\n'
'String\n'
'The path to a YAML file with a '
'single top-level map. The keys are '
'the words to discourage and the '
'values are suggestions of words to '
'replace them with.\n'
'\n'
'\n'
'phrase_substitutions_file\n'
'String\n'
'The path to a YAML file with a '
'single top-level map. The keys are '
'phrases to discourage and the '
'values are suggestions of phrases '
'to replace them with.\n'
'\n'
'\n'
'\n'
'You can add an exemption to a '
'specific discouraged word/phrase '
'rule with an HTML comment. The '
'exemption applies to the whole '
'output (HTML) file in which it '
'appears.\n'
'Maybe the word "will" is a '
'discouraged word, but you really '
'want to use it here without '
'flagging it as a violation? Adding '
'a comment like this <!-- '
'STYLE_OVERRIDE: will --> makes it '
'so.\n'
'\n'
'Spell Checking¶\n'
'Dactyl uses pyspellchecker to '
'report possible spelling errors '
'and suggest corrections. The '
'built-in dictionary is not very '
'thorough; you can extend it by '
'providing a dictionary file with '
'more words. Spell checking is '
'case-insensitive.\n'
'If you want the spell checker to '
'skip a page, put '
'skip_spell_checker: true in the '
'page definition.\n'
'If you want to ignore one or more '
'words on a single page only, add a '
'comment such as the following '
'anywhere in the page:\n'
'<!-- IGNORE_SPELLING: '
'affectednodes, creatednode, '
'deletednode, modifiednode -->\n'
'\n'
'To extend the built-in dictionary '
'used for all files, add the '
'following field to the config. '
'(You cannot remove words from the '
'built-in dictionary.)\n'
'\n'
'\n'
'\n'
'Field\n'
'Value\n'
'Description\n'
'\n'
'\n'
'\n'
'\n'
'spelling_file\n'
'String\n'
'Path to a text file with words to '
'add to the dictionary. Each line '
'of the file should contain a '
'single word (case-insensitive).\n'
'\n'
'\n'
'\n'
'Length Metrics¶\n'
'Dactyl reports the number of '
'characters of text, number of '
'sentences, and number of words in '
'each document. These counts only '
'include text contents (the parts '
'generated from Markdown). They do '
'not include code samples (not even '
'inlined code words), or '
'images/figures. The sentence '
'counts are estimates. Headings, '
'list items, and table cells each '
'count as one sentence in these '
'metrics. The summary includes the '
'averages across all pages, and the '
'stats for the three longest and '
'shortest pages.\n'
'These metrics are intended to be '
'helpful for choosing documents '
'that would be better off combined '
'or split up. They can also be '
'useful for interpreting '
'readability scores, which tend to '
'be less reliable for very short '
'documents.\n'
'Readability Scores¶\n'
'The style checker reports '
'readability scores based on '
'several formulas implemented in '
'the textstat library. These can '
'help you identify documents with a '
'high proportion of big words and '
'long sentences.\n'
'\n'
'Caution: Readability formulas are '
'not very smart. Trying to get a '
'high readability score can '
'actually decrease the clarity of '
"your writing if you aren't mindful "
'of other factors. Things '
"readability formulas usually don't "
'take into account include: '
'brevity; complexity of the '
'high-level structure; logical '
'connections such as cause and '
'effect; and precise use of '
'language. They tend to score '
'tables and bulleted lists badly '
'even though those structure are '
'very helpful for actual '
'readability.\n'
'\n'
'By default, Dactyl prints the '
'readability scores for each page '
'as it analyzes them. The -q option '
'hides this output. The summary at '
'the end lists the average scores '
'for all pages analyzed and the '
'three pages with the worst Flesch '
'Reading Ease scores.\n'
'Readability Goals¶\n'
'You can set readability goals for '
'individual pages or an entire '
'target by adding the '
'readability_goals field. This '
'field should contain a map of '
'readability metrics to target '
'scores. Goals defined for '
'individual pages override goals '
'set for the entire target. Dactyl '
"compares a page's readability "
'scores to any goals set and '
'reports a list of pages that '
'failed their goals in the summary. '
"The goal passes if the page's "
'score is equal better (easier to '
'read) than the stated goal value, '
'and fails otherwise. For Flesch '
'Reading Ease, higher scores '
'represent better readability; for '
'the other tests, lower scores '
'represent better readability.\n'
'Note: Since very short pages tend '
'to have inconsistent and '
'unreliable readability scores, '
'Dactyl does not calculate '
'readability scores for pages with '
'fewer than 10 "sentences". (Bullet '
'points, headings, and table cells '
'each count as separate "sentences" '
'for this purpose.)\n'
'Example configuration:\n'
'targets:\n'
'\n'
' - name: my-target\n'
' display_name: Example Target\n'
' readability_goals:\n'
' flesch_reading_ease: 50\n'
' '
'automated_readability_index: 12\n'
'\n'
'The available readability tests '
'are:\n'
'\n'
'\n'
'\n'
'Field Name\n'
'Details\n'
'\n'
'\n'
'\n'
'\n'
'flesch_reading_ease\n'
'Flesch reading ease. Maximum score '
'121.22; no limit on how negative '
'the score can be.\n'
'\n'
'\n'
'smog_index\n'
'SMOG grade. Gives an estimated '
'grade level.\n'
'\n'
'\n'
'coleman_liau_index\n'
'Coleman-Liau index. Gives an '
'estimated grade level.\n'
'\n'
'\n'
'automated_readability_index\n'
'Automated readability index. Gives '
'an estimated grade level.\n'
'\n'
'\n'
'dale_chall_readability_score\n'
'Dale-Chall readability formula. '
'Decimal representing difficulty; '
'lower values map to lower grade '
'levels.\n'
'\n'
'\n'
'linsear_write_formula\n'
'Linsear Write formula. Gives an '
'estimated grade level.\n'
'\n'
'\n'
'gunning_fog\n'
'Gunning fog index. Gives an '
'estimated grade level.\n'
'\n'
'\n'
'\n'
'Estimated grade levels are based '
'on the United States school system '
'and are given as decimal '
'approximations. For example, 11.5 '
'represents somewhere between 11th '
'and 12th grade (high school junior '
'to senior).',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'blurb': 'Dactyl has the ability to build JSON '
'formatted for upload to ElasticSearch '
'and even upload it directly.',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'ElasticSearch Compatibility¶': '#elasticsearch-compatibility',
'ElasticSearch JSON Templates¶': '#elasticsearch-json-templates'},
'hover_anchors': '¶',
'html': 'elasticsearch.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d336f70>,
'md': 'usage/elasticsearch.md',
'name': 'ElasticSearch Compatibility',
'parent': 'usage.html',
'plaintext': 'ElasticSearch Compatibility¶\n'
'Dactyl has the ability to build '
'JSON formatted for upload to '
'ElasticSearch and even upload it '
'directly.\n'
'To build JSON files for upload to '
'ElasticSearch, use the --es mode:\n'
'dactyl_build --es\n'
'\n'
'This writes files to the usual '
'output directory using an '
'ElasticSearch JSON template. '
'Dactyl skips any files that do not '
'have a md source parameter in this '
'mode. The output filenames are the '
"pages' html filenames, except "
'ending in .json instead of .html. '
'You can specify a custom template '
'for these JSON files using the '
'top-level default_es_template '
'field in the config file. This '
'template must be a valid JSON file '
'and has several special properties '
'as described in ElasticSearch JSON '
'Templates.\n'
'Dactyl can also upload these files '
'directly to an ElasticSearch '
'instance, even when building for '
'another mode. For example, to '
'build the HTML version of a target '
'named filterdemos but also upload '
"that target's JSON-formatted data "
'to an ElasticSearch instance:\n'
'dactyl_build -t filterdemos --html '
'--es_upload '
'https://my-es-instance.example.com:9200\n'
'\n'
'The parameter to --es_upload '
'should be the base URL of your '
'ElasticSearch index. You can omit '
'the parameter to use the default '
'base URL of '
'http://localhost:9200.\n'
'ElasticSearch JSON Templates¶\n'
'Dactyl has a special format for '
'JSON templates meant for creating '
'ElasticSearch data. These '
'templates must be valid JSON and '
'are processed according to the '
'following rules:\n'
'\n'
"Any strings in the fields' values "
'are "preprocessed" in a similar '
'context to the Jinja2-based '
'Markdown preprocessor. For '
'example, the string ElasticSearch '
'Compatibility evaluates to the '
"page's name.\n"
'Any object containing the key '
'__dactyl_eval__ is evaluated as a '
'Python expression. The object is '
'replaced with the results of the '
'expression, with lists becoming '
'JSON arrays and dictionaries '
'becoming JSON objects.\n'
'The above rules apply recursively '
'to values nested in arrays and '
'objects. All other values are '
'preserved literally.\n'
'\n'
'The context provided to the '
'preprocessing and to the '
'__dactyl_eval__ expressions is the '
'same and contains the following:\n'
'\n'
'\n'
'\n'
'Field\n'
'Python Type\n'
'Description\n'
'\n'
'\n'
'\n'
'\n'
'currentpage\n'
'dict\n'
'The current page definition '
'(usually derived from the config '
'file)\n'
'\n'
'\n'
'target\n'
'dict\n'
'The current target definition '
'(usually derived from the config '
'file)\n'
'\n'
'\n'
'categories\n'
'list\n'
'A list of unique category values '
'used by pages in the current '
'target, in order of appearance.\n'
'\n'
'\n'
'page_filters\n'
'list\n'
'A list of the names of Dactyl '
'filters applied to the current '
'page.\n'
'\n'
'\n'
'mode\n'
'str\n'
'Always equal to es in this '
'context\n'
'\n'
'\n'
'current_time\n'
'str\n'
'The current time, in the '
'time_format specified in the '
'config. (Defaults to YYYY-MM-DD)\n'
'\n'
'\n'
'bypass_errors\n'
'bool\n'
'If true, this build is running '
'with the option to continue '
'through errors where possible.\n'
'\n'
'\n',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'__dactyl_provided_filename__': True,
'blurb': 'Dactyl can parse an OpenAPI v3.0 '
'specification to generate API '
'documentation for the API that '
'specification describes, including API '
'methods and object schemas.',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Ad-Hoc Usage¶': '#ad-hoc-usage',
'Config File¶': '#config-file',
'Custom Templates¶': '#custom-templates',
'OpenAPI Specifications¶': '#openapi-specifications'},
'hover_anchors': '¶',
'html': 'openapi.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a040>,
'md': 'usage/openapi.md',
'name': 'OpenAPI Specifications',
'parent': 'usage.html',
'plaintext': 'OpenAPI Specifications¶\n'
'Dactyl can parse an OpenAPI v3.0 '
'specification to generate API '
'documentation for the API that '
'specification describes, including '
'API methods and object schemas.\n'
'Ad-Hoc Usage¶\n'
'You can use the --openapi '
'<specfile> parameter to build a '
'single target from\n'
'dactyl_build --openapi '
'openapi.yaml\n'
'\n'
'You can combine this with --md or '
'--pdf to output the generated '
'documentation in Markdown or PDF '
'format, respectively.\n'
'Config File¶\n'
'You can add a special entry to the '
'pages array to represent an API '
'reference; Dactyl will expand that '
'file into multiple pages that each '
'inherit any fields of this entry. '
'For example:\n'
'- openapi_specification: '
'https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml\n'
' api_slug: petstore\n'
' foo: bar\n'
' targets:\n'
' - baz\n'
'\n'
'The api_slug field is optional, '
'and provides a prefix that gets '
'used for a bunch of file names and '
'stuff. You can use the other '
'fields to specify which HTML '
'templates to use or to pass more '
'info to those templates to control '
'how they display.\n'
'The generated pages are:\n'
'\n'
'An "All Methods" table of '
'contents, listing every path '
'operation in the paths of the '
'OpenAPI specification.\n'
'"Tag Methods" table of contents '
'pages for each tag used in the '
'OpenAPI specification.\n'
'Pages for all "API Methods" (path '
'operations) in paths of the '
'OpenAPI specification.\n'
'A "Data Types" table of contents, '
'listing every data type defined in '
'the schema section of the OpenAPI '
'specification.\n'
'Individual pages for each data '
'type in the OpenAPI '
"specification's schema section.\n"
'\n'
'Custom Templates¶\n'
'You can override the templates '
'used for generated OpenAPI pages '
'to adjust how the Markdown is '
'generated.\n'
'In the page or target definition '
'of your config file, set the '
'openapi_md_template_path field to '
'a path that contains the following '
'templates:\n'
'\n'
'\n'
'\n'
'Filename\n'
'Template for...\n'
'\n'
'\n'
'\n'
'\n'
'template-openapi_data_type.md\n'
'Each individual data type in the '
"spec's schema section.\n"
'\n'
'\n'
'template-openapi_data_types_toc.md\n'
'Table of contents for the data '
'types.\n'
'\n'
'\n'
'template-openapi_endpoint_tag_toc.md\n'
'Table of contents for each '
'endpoint tag in the spec.\n'
'\n'
'\n'
'template-openapi_endpoint_toc.md\n'
'Table of contents for all '
'endpoints and tags.\n'
'\n'
'\n'
'template-openapi_endpoint.md\n'
'Table of contents for each '
'individual endpoint in the paths '
'section.\n'
'\n'
'\n'
'\n'
'These templates use Jinja syntax.',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']}],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Ad-Hoc Usage¶': '#ad-hoc-usage',
'Building Markdown¶': '#building-markdown',
'Building Only One Page¶': '#building-only-one-page',
'Building PDF¶': '#building-pdf',
'Listing Available Targets¶': '#listing-available-targets',
'Specifying a Config File¶': '#specifying-a-config-file',
'Specifying a Target¶': '#specifying-a-target',
'Static Files¶': '#static-files',
'Usage¶': '#usage',
'Watch Mode¶': '#watch-mode'},
'hover_anchors': '¶',
'html': 'usage.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d336d30>,
'md': 'usage/usage.md',
'name': 'Usage',
'parent': 'index.html',
'plaintext': 'Usage¶\n'
'Dactyl is intended to be used with a config file '
'(typically dactyl-config.yml) that specifies a '
'full list of files to build with necessary '
"metadata and other config. So, if you've got "
'this set up, you can run Dactyl like this:\n'
'dactyl_build\n'
'\n'
'By default, this outputs HTML. You can also '
'build a PDF or even Markdown. For a full list of '
"Dactyl's commandline options, use the -h "
'parameter.\n'
'Ad-Hoc Usage¶\n'
'Simple ("Ad-Hoc") usage:\n'
'$ dactyl_build --pages input1.md input2.md\n'
'\n'
'By default, the resulting HTML pages are written '
'to a folder called out/ in the current working '
'directory. You can specify a different output '
'path in the config file or by using the -o '
'parameter.\n'
'Building PDF¶\n'
'Dactyl generates PDFs by making temporary HTML '
'files and running Prince. Use the --pdf command '
'to generate a PDF. Dactyl tries to come up with '
'a sensible output filename by default, or you '
'can provide one (which must end in .pdf):\n'
'$ dactyl_build --pages input1.md input2.md --pdf '
'MyGuide.pdf\n'
'\n'
'Specifying a Config File¶\n'
'By default, Dactyl looks for a config file named '
'dactyl-config.yml in the current working '
'directory. You can specify an alternate config '
'file with the -c or --config parameter:\n'
'$ dactyl_build -c path/to/alt-config.yml\n'
'\n'
'For more information on configuration, see '
'Configuration and the examples folder.\n'
'Specifying a Target¶\n'
'If your config file contains more than one '
'target, Dactyl builds the first one by default. '
'You can specify a different target by passing '
'its name value with the -t parameter:\n'
'$ dactyl_build -t non-default-target\n'
'\n'
'Static Files¶\n'
'Your templates may require certain static files '
'(such as JavaScript, CSS, and images) to display '
'properly. Your content may have its own static '
'files (such as diagrams and figures). By '
'default, Dactyl assumes that templates have '
'static files in the assets/ folder. You can '
'configure this path and also specify one or more '
'paths to static files referenced by your '
'content. When you build, Dactyl copies files '
'from these folders to the output folder by '
"default depending on which mode you're "
'building:\n'
'\n'
'\n'
'\n'
'Build Mode\n'
'Files copied to output folder by default\n'
'\n'
'\n'
'\n'
'\n'
'HTML\n'
'Both template and content static files\n'
'\n'
'\n'
'PDF\n'
'Neither template nor content static files '
'(cannot be overridden)\n'
'\n'
'\n'
'Markdown\n'
'Content static files only\n'
'\n'
'\n'
'ElasticSearch JSON\n'
'Neither template nor content static files\n'
'\n'
'\n'
'\n'
'You can use a commandline flag to explicitly '
'specify what gets copied to the output folder, '
'except in the case of PDF. (In PDF mode, Dactyl '
'writes only the final PDF to the output folder.) '
'The flags are as follows:\n'
'\n'
'\n'
'\n'
'Flag (long version)\n'
'Short version\n'
'Meaning\n'
'\n'
'\n'
'\n'
'\n'
'--copy_static\n'
'-s\n'
'Copy all static files to the out dir.\n'
'\n'
'\n'
'--no_static\n'
'-S\n'
"Don't copy any static files to the out dir.\n"
'\n'
'\n'
'--template_static\n'
'-T\n'
"Copy only templates' static files to the out "
'dir\n'
'\n'
'\n'
'--content_static\n'
'-C\n'
"Copy only the content's static files to the out "
'dir\n'
'\n'
'\n'
'\n'
'The following config file parameters control '
'what paths Dactyl checks for static content:\n'
'\n'
'\n'
'\n'
'Field\n'
'Default\n'
'Description\n'
'\n'
'\n'
'\n'
'\n'
'template_static_path\n'
'assets/\n'
'Static files belonging to the templates.\n'
'\n'
'\n'
'content_static_path\n'
'(None)\n'
'Static files belonging to content. This can be a '
'single folder path, as a string, or an array of '
'paths to files or folders. Dactyl copies all '
'files and folders (regardless of whether the '
'current target uses them).\n'
'\n'
'\n'
'\n'
'Listing Available Targets¶\n'
'If you have a lot of targets, it can be hard to '
'remember what the short names for each are. If '
'you provide the -l flag, Dactyl will list '
'available targets and then quit without doing '
'anything:\n'
'$ dactyl_build -l\n'
'tests Dactyl Test Suite\n'
'rc-install Ripple Connect v2.6.3 '
'Installation Guide\n'
'rc-release-notes \n'
'kc-rt-faq Ripple Trade Migration FAQ\n'
'\n'
'Building Markdown¶\n'
'This mode runs the pre-processor only, so you '
'can generate Markdown files that are more likely '
'to display properly in conventional Markdown '
'parsers (like the one built into GitHub). Use '
'the --md flag to output Markdown files, skipping '
'the HTML/PDF templates entirely.\n'
'$ dactyl_build --md\n'
'\n'
'Building Only One Page¶\n'
'If you only want to build a single page, you can '
'use the --only flag, followed by the filename '
'you want to build (either the input filename '
'ending in .md or the output filename ending in '
'.html):\n'
'dactyl_build --only index.html --pdf\n'
'\n'
'This command can be combined with the --pdf or '
'--md flags. You can also use it with the '
'--target setting (in case you want the context '
"from the target even though you're only building "
'one page.)\n'
'Watch Mode¶\n'
'You can use the -w flag to make Dactyl run '
'continuously, watching for changes to its input '
'templates or markdown files. Whenever it detects '
'that a file has changed, Dactyl automatically '
'rebuilds the output in whatever the current mode '
'is, (HTML, PDF, or Markdown).\n'
'To be detected as a change, the file has to '
'match one of the following patterns:\n'
'*.md\n'
'*/code_samples/*\n'
'template-*.html\n'
'\n'
'Beware: some configurations can lead to an '
'infinite loop. (For example, if your output '
'directory is a subdirectory of your content '
'directory and you use Dactyl in --md mode.)\n'
'Limitations: Watch mode can be combined with '
'--only, but re-builds the page even when it '
'detects changes to unrelated pages. Watch mode '
"doesn't detect changes to the config file, "
'static files, or filters.\n'
'To stop watching, interrupt the Dactyl process '
'(Ctrl-C in most terminals).',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'blurb': '',
'category': 'Features',
'children': [{'blurb': 'Dactyl automatically adds syntax '
'highlighting to code blocks.',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Code Highlighting¶': '#code-highlighting',
'Disabling¶': '#disabling',
'Languages¶': '#languages',
'Requirements¶': '#requirements'},
'hover_anchors': '¶',
'html': 'code-highlighting.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a160>,
'md': 'code-highlighting.md',
'name': 'Code Highlighting',
'parent': 'features.html',
'plaintext': 'Code Highlighting¶\n'
'Dactyl automatically adds syntax '
'highlighting to code blocks when '
'it parses Markdown, using the '
'Pygments-derived CodeHilite '
'extension. Parsing the syntax '
'highlighting at compile time like '
'this is faster and less work for '
"readers' computers than in-browser "
'syntax highlighting such as using '
'highlight.js. (If you prefer '
"highlight.js's output, though, you "
'can still run it to overwrite '
"Dactyl's syntax highlighting.)\n"
'Example of a code segment colored '
"by Dactyl's built-in "
'highlighting:\n'
'unacceptable_chars = '
're.compile(r"[^A-Za-z0-9._ ]+")\n'
'whitespace_regex = '
're.compile(r"\\s+")\n'
'def slugify(s):\n'
' s = re.sub(unacceptable_chars, '
'"", s)\n'
' s = re.sub(whitespace_regex, '
'"_", s)\n'
' if not s:\n'
' s = "_"\n'
' return s\n'
'\n'
'Requirements¶\n'
'The highlighting requires a '
'stylesheet to define the colors '
"and styles used. Dactyl's default "
'stylesheet includes an example or '
'you can define your own. You can '
"output one of Pygments' default "
'stylesheets from the commandline '
'as in the following example:\n'
'$ pygmentize -S default -f html -a '
'.codehilite > default.css\n'
'\n'
'Languages¶\n'
"Dactyl's code highlighting "
'supports the same programming '
'languages that Pygments supports. '
'By default it attempts to '
'auto-detect the language, but you '
'can add a language code to the '
'first line of a fenced code block '
'to specify the language.\n'
'Example code:\n'
'```js\n'
'function slugify(s) {\n'
' const unacceptable_chars = '
'/[^A-Za-z0-9._ ]+/\n'
' const whitespace_regex = /\\s+/\n'
' s = '
's.replace(unacceptable_chars, "")\n'
' s = s.replace(whitespace_regex, '
'"_")\n'
' s = s.toLowerCase()\n'
' if (!s) {\n'
' s = "_"\n'
' }\n'
' return s\n'
'}\n'
'```\n'
'\n'
'Output:\n'
'function slugify(s) {\n'
' const unacceptable_chars = '
'/[^A-Za-z0-9._ ]+/\n'
' const whitespace_regex = /\\s+/\n'
' s = '
's.replace(unacceptable_chars, "")\n'
' s = s.replace(whitespace_regex, '
'"_")\n'
' s = s.toLowerCase()\n'
' if (!s) {\n'
' s = "_"\n'
' }\n'
' return s\n'
'}\n'
'\n'
'Disabling¶\n'
'If for some reason you want to '
'turn off syntax highlighting, you '
'can add no_highlighting: true to '
'your config file at the global, '
'target, or page level.',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'__dactyl_provided_filename__': True,
'blurb': 'This page demonstrates including a '
"file using the preprocessor's include "
'syntax. The path to including a file '
'is always relative to the content_path '
'from the config.',
'category': 'Features',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Includes and Filters¶': '#includes-and-filters',
'Includes¶': '#includes',
'Other Stuff¶': '#other-stuff',
'With Conditionals¶': '#with-conditionals'},
'hover_anchors': '¶',
'html': 'includes.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a1f0>,
'md': 'includes.md',
'name': 'Includes',
'parent': 'features.html',
'plaintext': 'Includes¶\n'
'This page demonstrates including a '
"file using the preprocessor's "
'include syntax. The path to '
'including a file is always '
'relative to the content_path from '
'the config.\n'
'Example code:\n'
"{% include 'includes/reusable.md' "
'%}\n'
'\n'
'Results:\n'
'This snippet of text is reusable '
'and can be included multiple times '
'as needed, while being sourced '
'from a single file in all cases.\n'
'With Conditionals¶\n'
'Sometimes you want to use a block '
'of text with slight differences in '
'different contexts. You can use '
'conditionals to define the '
'different text to appear or not '
'depending on where the file is '
'being included. In most cases you '
'can check some property of the '
'currentpage or target, but in case '
"you can't, the set tag can help.\n"
'Example code:\n'
'{% set extended = True %}\n'
"{% include 'includes/reusable.md' "
'%}\n'
'\n'
'Results:\n'
'This snippet of text is reusable '
'and can be included multiple times '
'as needed, while being sourced '
'from a single file in all cases.\n'
'This is the extended version.\n'
'Includes and Filters¶\n'
'If you include a page that is '
'written to use a filter, you might '
'get weird results if the current '
"page / target don't run the "
'filter.\n'
'Other Stuff¶\n'
'Includes are part of '
'preprocessing, so you can do '
'things like making one file that '
'has all your Markdown reference '
'links, and including that in all '
'your pages to make the reference '
'links always available.\n'
'Reader exercise: make your own '
'filter to automatically include a '
'page at the end of another page!',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'blurb': 'Frontmatter is a set of YAML keys and '
'values to start a Markdown file, set '
'off by two lines of ---. For example, '
'this page has the following '
'frontmatter:',
'categories': ['Tests',
'Dactyl ignores categories beyond '
'the first'],
'category': 'Tests',
'children': [],
'demote_headers_pdf_only': True,
'desc': 'This file has Jekyll-style frontmatter',
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Frontmatter¶': '#frontmatter'},
'hover_anchors': '¶',
'html': 'frontmatter.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a280>,
'md': 'frontmatter.md',
'name': 'Frontmatter',
'parent': 'features.html',
'plaintext': 'Frontmatter¶\n'
'Frontmatter is a set of YAML keys '
'and values to start a Markdown '
'file, set off by two lines of ---. '
'For example, this page has the '
'following frontmatter:\n'
'---\n'
'desc: This file has Jekyll-style '
'frontmatter\n'
'categories: ["Tests", "Dactyl '
'ignores categories beyond the '
'first"]\n'
'---\n'
'\n'
'The frontmatter can be referenced '
'by the preprocessor and by '
'templates. For example:\n'
'> Description: '
'{{currentpage.desc}}\n'
'\n'
'Results:\n'
'\n'
'Description: This file has '
'Jekyll-style frontmatter\n'
'\n'
'Caution: If you include a page, '
'the frontmatter of the included '
'page is not available to the '
'including page.',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'blurb': 'You can provide or override fields of '
'the target using the --vars parameter.',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Commandline Variables¶': '#commandline-variables'},
'hover_anchors': '¶',
'html': 'cli-vars.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a310>,
'md': 'cli-vars.md',
'name': 'Commandline Variables',
'parent': 'features.html',
'plaintext': 'Commandline Variables¶\n'
'You can provide or override fields '
'of the target using the --vars '
'parameter.\n'
'For example, the following is the '
'output of {{target.foo}}: '
'fooooooo\n'
'And the following is the output of '
'{{target.bar}}: ``\n'
'Some things to know about these '
'variables:\n'
'\n'
'foo is defined in the config file '
'definition for the "everything" '
'target.\n'
'bar is not defined in the config '
'file.\n'
'\n'
'You should be able to change the '
'output of these variables using a '
'--vars argument containing either '
'inlined JSON or the filename of a '
'JSON file with the variables to '
'apply to the target. For example:\n'
'dactyl_build --vars \'{"foo": "FOO '
'VALUE", "bar": "BAR VALUE"}\'\n'
'\n'
'or:\n'
'echo \'{"foo": "FOO VALUE", "bar": '
'"BAR VALUE"}\' > some_vars.json\n'
'dactyl_build --vars '
'some_vars.json\n',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'__dactyl_provided_filename__': True,
'blurb': 'You can use the preprocessor to hide '
'or show certain content based on '
'various conditions. For example, you '
'can have a page used in multiple '
'targets, but omit certain portions '
'from the output in some targets. Or, '
'you can have text and markup that only '
'shows up in HTML mode but not PDF mode '
'or similar rules.',
'category': 'Features',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Conditionals¶': '#conditionals'},
'hover_anchors': '¶',
'html': 'conditionals.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a3a0>,
'md': 'conditionals.md',
'name': 'Conditionals',
'parent': 'features.html',
'plaintext': 'Conditionals¶\n'
'You can use the preprocessor to '
'hide or show certain content based '
'on various conditions. For '
'example, you can have a page used '
'in multiple targets, but omit '
'certain portions from the output '
'in some targets. Or, you can have '
'text and markup that only shows up '
'in HTML mode but not PDF mode or '
'similar rules.\n'
'You can use any of the fields '
'available to the preprocessor for '
'your conditionals, including '
'commandline variables and any '
'fields defined in the '
'frontmatter.\n'
'Example of printing different text '
'by :\n'
'{% if currentpage.condition == '
"'tests-2' %}\n"
'some text that only appears when '
'the "condition" field of the '
'current page is "tests-2"\n'
'{% else %}\n'
'some text that appears when not '
'tests-2\n'
'{% endif %}\n'
'\n'
'some text that always appears\n'
'\n'
'Result:\n'
'some text that appears when not '
'tests-2\n'
'some text that always appears\n'
'\n'
'Example of printing different text '
'in different\n'
"{% if mode == 'pdf' %}\n"
'This is PDF mode.\n'
"{% elif mode == 'html' %}\n"
'This is HTML mode.\n'
"{% elif mode == 'md' %}\n"
'This is MD mode (See also: '
'`--githubify`)\n'
"{% elif mode == 'es' %}\n"
'This is ElasticSearch indexing '
'mode (JSON).\n'
'{% else %}\n'
'We should not reach this case.\n'
'{% endif %}\n'
'\n'
'Result:\n'
'This is HTML mode.',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything', 'conditionals']},
{'__dactyl_provided_filename__': True,
'blurb': "Markdown's handling of lists and code "
'blocks is kind of ugly.',
'category': 'Features',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Lists and Code Blocks¶': '#lists-and-code-blocks',
'Things that Work¶': '#things-that-work',
"Things that don't work¶": '#things-that-dont-work'},
'hover_anchors': '¶',
'html': 'lists-and-codeblocks.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a430>,
'md': 'lists-and-codeblocks.md',
'name': 'Lists and Code Blocks Demo',
'parent': 'features.html',
'plaintext': 'Lists and Code Blocks¶\n'
"Markdown's handling of lists and "
'code blocks is kind of ugly.\n'
'Things that Work¶\n'
"Both Dactyl's markdown parser and "
"GitHub's parser handle this case "
'correctly when you use indented '
'(not fenced) code blocks, with '
'some necessary blank lines '
'between.\n'
'\n'
'\n'
'first list item\n'
'Descriptive text inside of 1st '
'list item (indented 4 spaces, '
'after a blank line):\n'
'Indented, non-fenced code block, '
'minimum 8 spaces indented\n'
'\n'
'More descriptive text inside of '
'1st list item (indented 4 spaces '
'again):\n'
'Indented, non-fenced code block, '
'minimum 8 spaces indented\n'
'\n'
'\n'
'\n'
'second list item\n'
'\n'
'\n'
'For the record, you have to indent '
'everything another 4 spaces if you '
'have a nested list, e.g.:\n'
'\n'
'\n'
'level one list\n'
'\n'
'level two list (4 spaces '
'indented)\n'
'\n'
'level two list item 2\n'
'Some more info on item 2\n'
'a code block inside 2\n'
'\n'
'\n'
'\n'
'\n'
'\n'
"Things that don't work¶\n"
'\n'
'This is the first item of a list.\n'
'\n'
'This is a\n'
' fenced\n'
' code\n'
' block\n'
'\n'
'\n'
'The list should resume from here, '
"but it's actually a new list "
'instead\n'
'Is this the third list item?\n'
" It still doesn't work if the\n"
' fenced code block\n'
' is itself indented\n'
'\n'
'"Fourth" list item.\n'
'code fences turn into inline code '
'if you indent them _and_ leave a '
'blank line\n'
"5. Also, don't number your lists "
'with letters in markdown\n'
"a. It won't get interpreted as a "
'list\n'
'b. they get interpreted as raw '
'text\n'
"1. so you can't put more things "
'nested in them\n'
'\n'
'c. and if you omit a blank line it '
'gets worse\n'
'd. the lines blur together\n'
'\n'
'\n'
'And then the list should resume.\n'
'\n',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'__dactyl_provided_filename__': True,
'blurb': 'GitHub-Flavored Markdown has some '
"stuff that Dactyl doesn't do and "
'vice-versa, and various edge cases '
'that the two may interpret '
'differently.',
'category': 'Features',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Code Blocks¶': '#code-blocks',
'GFM Features Not Supported¶': '#gfm-features-not-supported',
'GitHub Markdown Compatibility¶': '#github-markdown-compatibility',
'Header IDs¶': '#header-ids',
'Line Breaks¶': '#line-breaks',
'Preprocessing¶': '#preprocessing'},
'hover_anchors': '¶',
'html': 'gfm-compat.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a4c0>,
'md': 'gfm-compat.md',
'name': 'GitHub Markdown Compatibility',
'parent': 'features.html',
'plaintext': 'GitHub Markdown Compatibility¶\n'
'GitHub-Flavored Markdown has some '
"stuff that Dactyl doesn't do and "
'vice-versa, and various edge cases '
'that the two may interpret '
'differently.\n'
'\n'
'GFM Features Not Supported\n'
'Line Breaks\n'
'Preprocessing\n'
'Header IDs\n'
'Code Blocks\n'
'\n'
'GFM Features Not Supported¶\n'
"Dactyl doesn't do any of the "
'following:\n'
'\n'
'Automatically make URLs into '
'hyperlinks\n'
'Emoji codes\n'
'Task lists\n'
'[x] completed\n'
'[ ] incomplete\n'
'\n'
'\n'
'Automatic references to GitHub (or '
'GitLab) issues, commits, or '
'external resources\n'
'\n'
'Suggestion: Avoid using these.\n'
'Line Breaks¶\n'
'You can have hard-wrapped '
'paragraphs in Markdown. This\n'
'means that not every single-line '
'break introduces a\n'
'new paragraph (<p> tag). '
"Generally, we don't write\n"
'hard-wrapped text for docs, '
'though. (It introduces\n'
'unnecessary churn in diffs.)\n'
'Two paragraphs should be separated '
'by an empty line.\n'
'According to Markdown syntax, you '
'can force a mid-paragraph\n'
'line break by ending a line with '
'two spaces\n'
'as demonstrated in this '
'paragraph.\n'
'But watch out -- some editors '
'(like Atom) tend to strip off '
'trailing spaces!\n'
'Preprocessing¶\n'
'Dactyl does preprocessing with '
'Jinja, so you can do conditional '
"text and includes. GitHub doesn't "
'have stuff like that.\n'
'Suggestion: For docs that are '
'meant to be viewed on GitHub, use '
'Dactyl\'s "Githubify mode" (TODO: '
'better docs on that) to do '
'pre-processing only and export a '
'markdown file you can push '
'elsewhere. Be careful not to '
'overwrite the original (with the '
'prepropessing directives) with the '
'processed export version.\n'
'Caution: The pre-processing '
"doesn't know anything about "
'Markdown syntax, so it might catch '
'Jinja-esque syntax in things that '
"weren't meant to be interpreted as "
"such. Use Jinja's escaping syntax "
'to fix that. E.g.:\n'
'The {% raw %} block type leaves '
'things inside of it unprocessed.\n'
'You can also use the variable '
'delimiter to print a literal, e.g. '
"{{ '{{' }} will come out as {{\n"
'Header IDs¶\n'
'You can link to headers within a '
'markdown document because each '
'header has a unique ID based on '
'its text.\n'
'Beware of slight differences '
'across markdown parsers. In most '
"cases, Dactyl's header formula "
"matches GitHub's.\n"
'Caution: Header IDs are '
'case-sensitive and always lower '
'case, for both GitHub-Flavored and '
'Dactyl markdown.\n'
'For a detailed comparison of many '
'edge cases, see Header Stress Test '
'(Dactyl) vs. Header Stress Test '
'(GitHub Gist).\n'
'Code Blocks¶\n'
'You can do code blocks either by '
'the "indented" syntax or with code '
'fences.\n'
'Generally, we recommend using code '
'fences. Code blocks inside lists '
'are an exception where you should '
'use indentation to demarcate code '
'blocks.\n'
'Dactyl automatically does syntax '
'highlighting on included code '
'blocks. If you use a language '
'definition in the code blocks, '
'Dactyl uses that to apply the '
'correct syntax highlighting where '
'possible.',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'__dactyl_provided_filename__': True,
'blurb': 'This page demonstrates a variety of '
'edge cases for the generation of '
'automatic IDs from header text. '
"Dactyl's generated IDs match "
'GitHub-flavored Markdown (GFM) except '
'in cases where GFM generates invalid '
'IDs.',
'category': 'Features',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'2- Edit rippled-cfg¶': '#2-edit-rippledcfg',
'Failed to open /etc/opt/ripple/rippled-cfg¶': '#failed-to-open-etcoptripplerippledcfg',
'Header Stress Test¶': '#header-stress-test-2',
'Montréal, über, 12-89, Mère, Françoise, noël, 889¶': '#montréal-über-1289-mère-françoise-noël-889',
'Repeated Headers¶': '#repeated-headers',
'Some italic and bold text in the header-¶': '#some-italic-and-bold-text-in-the-header',
'What about angle brackets, a-k-a- < and > symbols?¶': '#what-about-angle-brackets-aka-and-symbols',
'XRP Ledgerの概要¶': '#xrp-ledgerの概要',
'account_info¶': '#account_info',
'n>1¶': '#n1',
"rippled Server Won't Start¶": '#rippled-server-wont-start',
'z͇͔̜̎̌͑ä̦̲́̃lg͖͎ọ̞̲̭̣̘̗ t̝̻̬̪͉͙͍̆̇͂ͮ̑̈̌ex͓̟̐̾t¶': '#zalgo-text',
'決済のためのデジタル資産¶': '#決済のためのデジタル資産-2',
'💩¶': '#_'},
'hover_anchors': '¶',
'html': 'header_stress_test.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a550>,
'md': 'header_stress_test.md',
'name': 'Header Stress Test',
'parent': 'features.html',
'plaintext': 'Header Stress Test¶\n'
'This page demonstrates a variety '
'of edge cases for the generation '
'of automatic IDs from header text. '
"Dactyl's generated IDs match "
'GitHub-flavored Markdown (GFM) '
'except in cases where GFM '
'generates invalid IDs.\n'
'2. Edit rippled.cfg¶\n'
'Lorem ipsum dolor amet seitan '
'succulents copper mug humblebrag. '
'Synth XOXO next level exercitation '
'intelligentsia farm-to-table '
'celiac four loko esse '
'reprehenderit artisan ennui migas '
'bitters. Plaid la croix prism man '
'bun. Roof party neutra butcher '
'heirloom fashion axe. Letterpress '
'semiotics aliquip, palo santo lomo '
'vice man braid reprehenderit nulla '
'raw denim put a bird on it '
'readymade. Everyday carry dolore '
'flexitarian, YOLO typewriter elit '
'hexagon XOXO cred bespoke '
'gochujang synth.\n'
"rippled Server Won't Start¶\n"
'Cloud bread franzen drinking '
'vinegar neutra you probably '
"haven't heard of them squid, "
'subway tile hoodie bicycle rights '
'in live-edge. Raclette cupidatat '
'aliqua meditation truffaut. '
'Dreamcatcher yuccie roof party '
'ramps, DIY hexagon aliquip '
'readymade aliqua PBR&B. Kitsch '
'chartreuse snackwave palo santo '
'anim air plant shabby chic. '
'Flexitarian meggings laborum, '
'truffaut retro nostrud post-ironic '
'trust fund adipisicing mollit '
'deserunt.\n'
'Failed to open '
'/etc/opt/ripple/rippled.cfg¶\n'
'Does the entire path get mashed '
'into a single run-on word?\n'
'account_info¶\n'
'Single underscore—does it stay or '
'does it go?\n'
'Some italic and bold text in the '
'header.¶\n'
"Formatting probably doesn't "
'contribute to the header text?\n'
'What about angle brackets, a.k.a. '
'< and > symbols?¶\n'
'n>1¶\n'
'How do you link that "n>1" header, '
"anyway? Turns out on GitHub it's "
'#n1.\n'
'XRP Ledgerの概要¶\n'
'XRP '
'Ledgerは、ピアツーピア・サーバーのネットワーク機能を備えた分散型の暗号台帳です。XRP '
'LedgerはXRPの土台となるものであり、世界中で使用されている様々な通貨の橋渡しをするために設計されたデジタル資産です。RippleはXRP '
'Ledgerの開発を主導し、「価値のインターネット」（情報が移動するようにお金が移動する世界）の実現に向けて鍵となる役割を果たすと期待されるXRPを推進しています。\n'
'決済のためのデジタル資産¶\n'
'XRPはXRP '
'Ledger固有のデジタル資産です。暗号鍵を持ち、インターネットに接続できる人は誰でも、XRPを受け取り、保持し、任意の人に送ることができます。XRPは他の通貨での取引をも容易にできる魅力的なブリッジ通貨として開発されました。XRPには次のような多くの特性があり、これにより他の多くのユースケースでも魅力的な資産となっています。\n'
'💩¶\n'
'👑📌🎇📘🔀👏🎏 👛🐩🌉🗽🔍💄 🐹🎯👤📭🏡🕖 🌅🎇💾📫🔃🌚 🌽🏪🌺🐰📛 '
'🕐🐵🌕👎🏯 👫🏄👻👊 🕦📅🎲🔄🐮🏤🏇👀🌰 👔👣🍒👠🎧🍮 💯🍪💣💔🍰 '
'💕🏪🐹🍡🐦🎋🐁 🏈📒🐽🍢📜 💆🕜📔💧🐥 👔🔠🎱👪. 📣🔂🎥🌛👌🐾 '
'🌔🐌🔋🏇🌵👄 🌅🔗💺🔣🐅👽 💞🐐🔎🌉🍌👸🍈 🍌🐸🐼📛🍁💤🍨 '
'🍚👣💮📒🔇 🎇🎥🔴🕑🕑🍊 🔃🐸👩🌼🐕 🍲🌠📆🔮 📹🐨🎻🍷🎭📼 '
'🔼🍳💎🌏 👉🔲👉📕 🎂🎊🐸🔺🔠 🔂🔣🐍🐆👛💂. 🌶🔱💝🌱🐀 '
'🔩👳🐟🐥👸 💷🌄🎶🌟🍲💃 🕙🔂🌞🔦 💔🍭💃🌁 🌆📕👈🐶📷 '
'🎴👩👤📉🕗🔊👌 🍊📟🔒🎻💃🎃 🔳🍇🔆🐢💈👧 🐲💀🍵🌱🔉 🐗📤🔼👫🔹 '
'🍥📷🏨🐟📴 💭🍂🐎🌕💼 📊💣💆🔚👵👔 🐁🏫\n'
'Montréal, über, 12.89, Mère, '
'Françoise, noël, 889¶\n'
'z͇͔̜̎̌͑ä̦̲́̃lg͖͎ọ̞̲̭̣̘̗ '
't̝̻̬̪͉͙͍̆̇͂ͮ̑̈̌ex͓̟̐̾t¶\n'
'Zalgo is to invoke the hive-mind '
'representing chaos. Invoking the '
'feeling of chaos. Without order.\n'
'Repeated Headers¶\n'
'Repeated headers should have '
'unique IDs. But do they?\n'
'Header Stress Test¶\n'
'Repeated.\n'
'Header Stress Test¶\n'
'Repeated again.\n'
'決済のためのデジタル資産¶\n'
'All-Japanese, repeated.\n'
'決済のためのデジタル資産¶\n'
'... again.',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'__dactyl_provided_filename__': True,
'blurb': '"Virtual Pages" are placeholders for '
'pages or websites that are not part of '
'the Dactyl site, but that you want to '
'link from within the Dactyl-generated '
"navigation. Dactyl's built-in "
'templates automatically create links '
'to virtual pages in the appropriate '
'places within the navigation.',
'category': 'Features',
'children': [{'blurb': 'This is a placeholder '
'that shows up in '
'navigation but does not '
'have an actual output '
'file. Use this if you '
'want to link to external '
'resources at a specific '
'place in your '
'navigation.',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'hover_anchors': '¶',
'html': 'https://dactyl.link/#',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a670>,
'name': 'Dactyl Homepage',
'parent': 'virtual-pages.html',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'blurb': 'This is an example of a '
'virtual page defined by '
'MD frontmatter.',
'category': 'Features',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'hover_anchors': '¶',
'html': 'https://dactyl.link/',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a700>,
'md': 'virtual-placeholder.md',
'name': 'Virtual Placeholder',
'parent': 'virtual-pages.html',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']}],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Virtual Pages¶': '#virtual-pages'},
'hover_anchors': '¶',
'html': 'virtual-pages.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a5e0>,
'md': 'virtual-pages.md',
'name': 'Virtual Pages',
'parent': 'features.html',
'plaintext': 'Virtual Pages¶\n'
'"Virtual Pages" are placeholders '
'for pages or websites that are not '
'part of the Dactyl site, but that '
'you want to link from within the '
'Dactyl-generated navigation. '
"Dactyl's built-in templates "
'automatically create links to '
'virtual pages in the appropriate '
'places within the navigation.\n'
'Dactyl does not build an '
'associated output HTML file for '
'these pages, so they are linked '
'from PDF builds but their contents '
'are not part of the generated PDF. '
'The link checker treats virtual '
'pages the same as other external '
'links, so it checks links to them '
'but not in the virtual pages.\n'
'The "Dactyl Homepage" link listed '
'under this page is an example of a '
'Virtual Page. To create a virtual '
'link, add a stanza such as the '
'following to the page array in '
'your config file:\n'
'- name: Dactyl Homepage\n'
' parent: virtual-pages.html\n'
' html: https://dactyl.link/\n'
' targets:\n'
' - everything\n'
'\n'
'Specifically, a virtual page is '
'any page with // in its html '
'attribute.\n'
'You can also define a virtual page '
'using a .md file with frontmatter. '
'For example, you could have a file '
'with the following contents:\n'
'---\n'
'html: https://dactyl.link/\n'
'blurb: This is an example of a '
'virtual page defined by MD '
'frontmatter.\n'
'category: Features\n'
'parent: virtual-pages.html\n'
'---\n'
'# Virtual Placeholder\n'
'\n'
'The actual Markdown contents of a '
'"virtual page" are mostly ignored. '
'However, they can be used to '
'provide metadata such as the title '
'and blurb used in navigation on '
'other pages.\n',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']}],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {},
'hover_anchors': '¶',
'html': 'features.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a0d0>,
'name': 'Features',
'parent': 'index.html',
'plaintext': '',
'section_header': True,
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything'],
'template': 'landing.html'},
{'__dactyl_provided_filename__': True,
'blurb': 'Dactyl supports additional custom post-processing '
'through the use of filters which are essentially '
'custom plugins. Filters can operate on the markdown '
"(after it's been pre-processed), on the raw HTML "
"(after it's been parsed), or on a BeautifulSoup "
'object representing the output HTML. Filters can '
'also export functions and values that are available '
'to the preprocessor.',
'category': 'Filters',
'children': [{'__dactyl_provided_filename__': True,
'blurb': 'Callouts are a specially-colored '
'blocks that call attention to '
'particular bits of information. They '
'might be special warnings, asides, or '
'other details. To use callouts, the '
'page (or target) has to have the '
'callouts filter enabled, then provide '
'syntax such as the following:',
'category': 'Filters',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers', 'callouts'],
'foo': 'fooooooo',
'headermap': {'Callouts Demonstration¶': '#callouts-demonstration',
'Cases to Avoid¶': '#cases-to-avoid',
'Custom Callout Types¶': '#custom-callout-types',
'Multiline Callouts¶': '#multiline-callouts'},
'hover_anchors': '¶',
'html': 'callouts.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a820>,
'md': 'filters/callouts.md',
'name': 'Callouts Demonstration',
'parent': 'filters.html',
'plaintext': 'Callouts Demonstration¶\n'
'Callouts are a specially-colored '
'blocks that call attention to '
'particular bits of information. '
'They might be special warnings, '
'asides, or other details. To use '
'callouts, the page (or target) has '
'to have the callouts filter '
'enabled, then provide syntax such '
'as the following:\n'
'**Tip:** This is a "Tip" callout, '
'styled with green and a checkmark '
'by default.\n'
'\n'
'Tip: This is a "Tip" callout, '
'styled with green and a checkmark '
'by default.\n'
'Note: Callouts have four types by '
'default: "Note", "Tip", "Caution", '
'and "Warning".\n'
'Caution: Be sure not to overuse '
'callouts.\n'
'Warning: Callouts are very '
'specific. **Note:** triggers a '
"callout; **Notes:** doesn't. The "
'colon is optional, though.\n'
'Multiline Callouts¶\n'
'\n'
'Tip: Multiline callouts with '
'blockquotes are now possible.\n'
'\n'
'Do this to include bulleted '
'lists.\n'
'Or other types of lists.\n'
'\n'
'\n'
'\n'
'Code example:\n'
'> **Tip:** Multiline callouts with '
'blockquotes are now possible.\n'
'>\n'
'> - Do this to include bulleted '
'lists.\n'
'> - Or other types of lists.\n'
'>\n'
'\n'
'If you have a callout word like '
'tip bolded mid-paragraph, it '
'should not become a callout.\n'
'\n'
'Please note that this also applies '
'to blockquotes.\n'
'\n'
'There is a difficult edge case for '
'blockquotes where a paragraph '
'other than the first one starts '
'with a callout keyword:\n'
'\n'
'This is the start of a blockquote '
'that is not, itself, a callout.\n'
'Note: This callout occurs in the '
'middle of a blockquote.\n'
'But the blockquote containing it '
'is not, itself, a callout.\n'
'\n'
'Also, note that you can cannot use '
'code fences in blockquotes.\n'
'\n'
'Caution: Code fences in '
"blockquotes don't work right.\n"
'js\n'
'if (true) {\n'
" console.log('this line of code "
"should be indented');\n"
'}\n'
'The code fence gets treated as '
'inlined code text instead. This is '
'a limitation of Python-Markdown.\n'
'\n'
'You can, however, use indented '
'code blocks in blockquotes:\n'
'\n'
'Tip: To get a proper code block in '
'a blockquote, provide a single\n'
'line of just the blockquote intro '
'>, and indent the code block 5 '
'spaces.\n'
'print("Hello world!")\n'
'if True:\n'
' print("Note that extra spaces '
'beyond the initial 5 carry '
'over.")\n'
'\n'
'To continue the block quote '
'afterwords, leave a near-blank '
'line similarly.\n'
'Do not use code fences in a '
"blockquote: they don't work as "
'expected.\n'
'\n'
'Cases to Avoid¶\n'
'\n'
'In a list, the callout applies to '
'the whole list item.\n'
'Tip: You can have callouts nested '
'in a list.\n'
"Warning: You probably wouldn't "
'like what happens if you nest '
'callouts in list items that are '
'already callouts.\n'
'\n'
'\n'
'\n'
'\n'
'One more point. Note: The callout '
"doesn't trigger if it's not at the "
'start of the element.\n'
'\n'
'\n'
'\n'
'\n'
'Table\n'
'Stuff\n'
'\n'
'\n'
'\n'
'\n'
'Warning: Callout syntax in table '
'cells is weird.\n'
"So it's probably best not to do "
'that.\n'
'\n'
'\n'
'Probably.\n'
'Caution: It could maybe work '
'better with better CSS.\n'
'\n'
'\n'
'\n'
'Custom Callout Types¶\n'
'You can define additional callout '
'types if you want. This requires '
'two pieces:\n'
'\n'
'A list of what words should '
'trigger a callout.\n'
'CSS styles for the relevant '
'callout types.\n'
'\n'
'To define custom callout classes, '
'write the trigger words '
'(case-insensitive) in your '
"project's Dactyl config file. This "
'overwrites the default list, so '
'include the default four if you '
'still want to use them. For '
'example:\n'
'callout_types:\n'
' - "tip"\n'
' - "ヒント" # equiv. of "Tip" in '
'Japanese (lit. "Hint")\n'
' - "note"\n'
' - "注記" # equiv of "Note" in '
'Japanese\n'
' - "caution"\n'
' - "注意" # equiv. of "Caution" in '
'Japanese\n'
' - "warning"\n'
' - "警告" # equiv. of "Warning" in '
'Japanese\n'
'\n'
'Any paragraph that starts with a '
'bold or italic section that '
'consists of only one of the listed '
'words triggers a callout. The '
'callout has two CSS classes:\n'
'\n'
'A general callout class. This is '
'dactyl-callout by default.\n'
'The word that triggered the '
'callout (for example, tip) in all '
'lowercase.\n'
'\n'
'You can customize the general '
'callout class with a config file '
'line such as the following:\n'
'callout_class: "my-callout-class"\n'
'\n'
'Finally, add the relevant CSS '
'styles to your stylesheet for the '
'new class. For example, the '
'default Dactyl stylesheet defines '
'the "Tip" and "ヒント" callout styles '
'as follows:\n'
'.dactyl-content .dactyl-callout {\n'
' border-style: solid;\n'
' border-radius: .25rem;\n'
' border-width: 1px;\n'
' border-left-width: 1px;\n'
' border-left-width: 4px;\n'
' padding: 5px;\n'
' padding-left: 5px;\n'
' padding-left: 25px;\n'
' page-break-inside: avoid;\n'
'}\n'
'\n'
'.dactyl-content '
'.dactyl-callout.tip, '
'.dactyl-content '
'.dactyl-callout.ヒント {\n'
' border-color: #28a745; /* '
'Green border */\n'
'}\n'
'\n'
'.dactyl-content '
'.dactyl-callout.tip > '
'strong:first-child::before,\n'
'.dactyl-content '
'.dactyl-callout.tip > p '
'strong:first-child::before,\n'
'.dactyl-content '
'.dactyl-callout.ヒント > '
'strong:first-child::before,\n'
'.dactyl-content '
'.dactyl-callout.ヒント > p '
'strong:first-child::before {\n'
' content: "\\f058"; /* '
'fontawesome check-circle icon */\n'
' font-family: FontAwesome;\n'
' color: #28a745;\n'
' margin-left: -20px;\n'
' padding-right: 5px;\n'
'}\n',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything', 'filterdemos']},
{'__dactyl_provided_filename__': True,
'blurb': 'Intelligent cross-references are a '
'feature designed to be a link when '
'they can be, and text directing people '
'to a different target (guide) if not. '
"Here's some examples for testing:",
'category': 'Filters',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers', 'xrefs'],
'foo': 'fooooooo',
'headermap': {'Anchors¶': '#anchors',
'Intelligent Cross-References¶': '#intelligent-cross-references'},
'hover_anchors': '¶',
'html': 'xrefs.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a8b0>,
'md': 'filters/xrefs.md',
'name': 'Intelligent Cross-References',
'parent': 'filters.html',
'plaintext': 'Intelligent Cross-References¶\n'
'Intelligent cross-references are a '
'feature designed to be a link when '
'they can be, and text directing '
'people to a different target '
"(guide) if not. Here's some "
'examples for testing:\n'
'You can link by HTML filename: \n'
'Or by MD filename: \n'
'If the MD filename is ambiguous, '
'you can specify the full path:\n'
'\n'
'For an example of an inline cross '
'reference, see .\n'
'Also, demonstrating that context, '
"spaces, and case mostly don't "
'matter:\n'
'\n'
'\n'
'(Above this should be a '
'cross-reference to the includes '
'test.)\n'
'\n'
'Anchors¶\n'
'You can use anchors but the '
'generated labels always use the '
'page name: \n'
'If you want to refer to a specific '
'anchor, the workaround is to use '
'an explicit label: Code Blocks\n'
'If the cross-reference appears in '
'multiple targets, Dactyl chooses '
'the first such target listed for '
'the file. For example, if you want '
'to refer to the Conditionals page '
'using the conditionals target '
'(when linking it from the '
'filterexamples target), you have '
'to change the order listed in the '
'config file. Dactyl will always '
'use the "everything" target since '
"that's the first one listed:\n"
'\n'
'If you want to specify a different '
'target, you have to use '
'conditional text in Jinja '
'templating syntax instead of smart '
'xrefs.',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything', 'filterdemos']},
{'__dactyl_provided_filename__': True,
'blurb': 'The buttonize filter makes some links '
'look like buttons if their link text '
'ends in a > sign.',
'category': 'Filters',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers', 'buttonize'],
'foo': 'fooooooo',
'headermap': {'Buttonize Filter¶': '#buttonize-filter'},
'hover_anchors': '¶',
'html': 'buttonize.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a940>,
'md': 'filters/buttonize.md',
'name': 'Buttonize Filter',
'parent': 'filters.html',
'plaintext': 'Buttonize Filter¶\n'
'The buttonize filter makes some '
'links look like buttons if their '
'link text ends in a > sign.\n'
'Markdown:\n'
'[Normal '
'Link](https://github.com/ripple/dactyl)\n'
'\n'
'[Button Link '
'>](http://github.com/ripple/dactyl)\n'
'\n'
'Results:\n'
'Normal Link\n'
'Button Link >',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything', 'filterdemos']},
{'__dactyl_provided_filename__': True,
'blurb': 'Uses shields.io to make badges out of '
'links. For example:',
'category': 'Filters',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers', 'badges'],
'foo': 'fooooooo',
'headermap': {'Badges¶': '#badges'},
'hover_anchors': '¶',
'html': 'badges.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a9d0>,
'md': 'filters/badges.md',
'name': 'Badges',
'parent': 'filters.html',
'plaintext': 'Badges¶\n'
'Uses shields.io to make badges out '
'of links. For example:\n'
'[badge: '
'orange](http://example.com/ '
'"BADGE_ORANGE")\n'
'\n'
'Results in a badge like this:\n'
'badge: orange\n'
'To make a badge, create a link '
'whose label is leftside: rightside '
'(separated by a colon (:) '
"character) and set the link's "
'title text to "BADGE_(COLOR)" '
'(all-caps) where "(COLOR)" is one '
'of the following:\n'
'\n'
'BRIGHTGREEN\n'
'GREEN\n'
'YELLOWGREEN\n'
'YELLOW\n'
'ORANGE\n'
'RED\n'
'LIGHTGREY\n'
'BLUE\n'
'Any 6-digit hexadecimal color '
'code. For example, BADGE_006633 '
'for Color:006633\n',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything', 'filterdemos']},
{'__dactyl_provided_filename__': True,
'blurb': 'The multi code-tabs filter lets you '
'list multiple code samples and have '
'them appear as tabs in the HTML '
'version. It looks like this:',
'category': 'Filters',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers', 'multicode_tabs'],
'foo': 'fooooooo',
'headermap': {'Multi Code-Tabs Filter¶': '#multi-code-tabs-filter',
'Syntax¶': '#syntax',
'With Custom Templates¶': '#with-custom-templates'},
'hover_anchors': '¶',
'html': 'multicode_tabs.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33aa60>,
'md': 'filters/multicode_tabs.md',
'name': 'Multi Code-Tabs Filter',
'parent': 'filters.html',
'plaintext': 'Multi Code-Tabs Filter¶\n'
'The multi code-tabs filter lets '
'you list multiple code samples and '
'have them appear as tabs in the '
'HTML version. It looks like this:\n'
'\n'
'Tab 1 Name\n'
'{\n'
' "id": 2,\n'
' "command": "account_info",\n'
' "account": '
'"r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",\n'
' "strict": true,\n'
' "ledger_index": "validated"\n'
'}\n'
'\n'
'Tab 2 Name\n'
'POST http://s1.ripple.com:51234/\n'
'{\n'
' "method": "account_info",\n'
' "params": [\n'
' {\n'
' "account": '
'"r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",\n'
' "strict": true,\n'
' "ledger_index": '
'"validated"\n'
' }\n'
' ]\n'
'}\n'
'\n'
'Tab 3 Name\n'
'rippled account_info '
'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59 '
'validated true\n'
'\n'
'\n'
'Syntax¶\n'
'To display code in tabs, use the '
'following syntax:\n'
'<!-- MULTICODE_BLOCK_START -->\n'
'\n'
'_First Tab Name_\n'
'\n'
'```js\n'
'console.log("First tab '
'contents");\n'
'```\n'
'\n'
'_Second Tab Name_\n'
'\n'
'```py\n'
'print("Second tab contents")\n'
'```\n'
'\n'
'<!-- MULTICODE_BLOCK_END -->\n'
'\n'
'There is no hard limit on the '
'number of tabs you can have. If '
'the total width of the tab names '
'gets too long for the viewscreen, '
'they get broken into multiple '
'lines, which may not look that '
'good depending on your CSS.\n'
'Tabs can only contain code blocks, '
'not other contents.\n'
'With Custom Templates¶\n'
'These tabs require some CSS and '
'JavaScript to work:\n'
'\n'
'multicode_tabs.js\n'
'dactyl-multicode_tabs.css\n'
'\n'
"If you're writing your own "
'templates, you need to include '
'these lines of code in your '
'project to get the tabs to display '
"properly. If you're using the "
'built-in templates, they load this '
"code automatically, so you don't "
'need to do anything special.',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything', 'filterdemos']},
{'__dactyl_provided_filename__': True,
'blurb': 'This filter adds an "external link" '
'icon to links to outside websites. '
"Well, it's not actually all that "
"smart. It doesn't know what website "
"it's on, so it adds the icon to any "
'link whose URL starts with http: or '
'https:. It also sets all external '
'links to open in a new tab/window.',
'category': 'Filters',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers',
'buttonize',
'external_links'],
'foo': 'fooooooo',
'headermap': {'External Links¶': '#external-links'},
'hover_anchors': '¶',
'html': 'external_links.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33aaf0>,
'md': 'filters/external_links.md',
'name': 'External Links',
'parent': 'filters.html',
'plaintext': 'External Links¶\n'
'This filter adds an "external '
'link" icon to links to outside '
"websites. Well, it's not actually "
"all that smart. It doesn't know "
"what website it's on, so it adds "
'the icon to any link whose URL '
'starts with http: or https:. It '
'also sets all external links to '
'open in a new tab/window.\n'
"A link to another page won't have "
'the icon.\n'
'If you try to combine this filter '
'with the button links filter >, '
'make sure buttonize runs first. '
'Otherwise, external links will not '
'get styled as buttons when '
'intended.',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything', 'filterdemos']}],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Filters¶': '#filters'},
'hover_anchors': '¶',
'html': 'filters.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a790>,
'md': 'filters/filters.md',
'name': 'Filters',
'parent': 'index.html',
'plaintext': 'Filters¶\n'
'Dactyl supports additional custom '
'post-processing through the use of filters which '
'are essentially custom plugins. Filters can '
"operate on the markdown (after it's been "
"pre-processed), on the raw HTML (after it's been "
'parsed), or on a BeautifulSoup object '
'representing the output HTML. Filters can also '
'export functions and values that are available '
'to the preprocessor.\n'
'Dactyl comes with several filters, which you can '
'enable in your config file. You can also write '
'your own filters. If you do, you must specify '
'the paths to the folder(s) containing your '
'filter files in the filter_paths array of the '
'config file.\n'
'To enable a filter for a target or page, set the '
'filters field of the config to be an array of '
'filter names, where the filter names are derived '
'from the Python source files in the format '
'filter_<filtername>.py. Filter names must be '
"valid Python variable names, so they can't start "
'with a numeral and must contain only '
'alphanumeric and underscore characters.\n'
'Dactyl automatically runs the following '
'functions from filter files (skipping any that '
"aren't defined):\n"
'\n'
'Before running the preprocessor on a page, '
"Dactyl adds all items from each filter's export "
'global dictionary to the preprocessor '
'environment.\n'
'Dactyl runs the filter_markdown(md, **kwargs) '
'function of each filter after the preprocessor. '
'This function receives the preprocessed markdown '
'as a string in the md argument and must return a '
'string with the markdown as filtered.\n'
'Dactyl runs the filter_html(html, **kwargs) '
'function after the markdown processor. This '
'function receives the parsed markdown content as '
'an HTML string in the html argument and must '
'return a string with the HTML as filtered.\n'
'Dactyl runs the filter_soup(soup, **kwargs) '
'function after the HTML filters. This function '
'is expected to directly modify the soup '
'argument, which contains a BeautifulSoup 4 '
'object representing the HTML contents.\n'
'\n'
'The keyword arguments (**kwargs) for the '
'functions may change in future versions. As of '
'Dactyl 0.5.0, the arguments are as follows:\n'
'\n'
'\n'
'\n'
'Field\n'
'Type\n'
'Description\n'
'\n'
'\n'
'\n'
'\n'
'currentpage\n'
'Dict\n'
'The current page, as defined in the config file '
'plus values inherited from the current target '
'and any processing or calculations. (For '
'example, Dactyl automatically adds a name field '
"if one isn't present.)\n"
'\n'
'\n'
'categories\n'
'List\n'
'A de-duplicated, ordered list of category fields '
'present among pages in this target.\n'
'\n'
'\n'
'pages\n'
'List\n'
'A list of page objects for all pages in the '
'current target, in the same order they appear in '
'the config file.\n'
'\n'
'\n'
'target\n'
'Dict\n'
'The current target definition, as derived from '
'the config file.\n'
'\n'
'\n'
'current_time\n'
'String\n'
'The time this build was started. The format is '
"defined by your config's global time_format "
'field (in stftime format), defaulting to '
'YYYY-MM-DD.\n'
'\n'
'\n'
'mode\n'
'String\n'
'Either html, pdf, or md depending on what output '
'Dactyl is building.\n'
'\n'
'\n'
'config\n'
'Dict\n'
'The global config object, based on the config '
'file plus any commandline switches.\n'
'\n'
'\n'
'logger\n'
'Logger\n'
'The logging object Dactyl uses, with the '
'verbosity set to match user input.\n'
'\n'
'\n',
'section_header': True,
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything', 'filterdemos'],
'template': 'landing.html'},
{'blurb': 'Dactyl is designed to be customized and extended to '
"each individual project's needs. These pages "
'demonstrate some ways you can extend Dactyl.',
'category': 'Extending',
'children': [{'__dactyl_provided_filename__': True,
'blurb': 'Dactyl provides built-in templates '
'that are fairly full-featured, but you '
'can also write your own, including '
'ones that extent or repurpose parts of '
'the built-in templates, and get '
'updates automatically when Dactyl is '
'updated. As an example, this page uses '
'a custom template that addsa "related '
'pages" module to the right-hand '
'sidebar.',
'category': 'Extending',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Built-In Templates¶': '#built-in-templates',
'Children Module¶': '#children-module',
'Module Templates¶': '#module-templates',
'Page Templates¶': '#page-templates',
'Template Data¶': '#template-data',
'Templates¶': '#templates',
'Tree Nav Module¶': '#tree-nav-module'},
'hover_anchors': '¶',
'html': 'templates.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33ac10>,
'md': 'extending/templates.md',
'name': 'Templates',
'parent': 'extending-index.html',
'plaintext': 'Templates¶\n'
'Dactyl provides built-in templates '
'that are fairly full-featured, but '
'you can also write your own, '
'including ones that extent or '
'repurpose parts of the built-in '
'templates, and get updates '
'automatically when Dactyl is '
'updated. As an example, this page '
'uses a custom template that addsa '
'"related pages" module to the '
'right-hand sidebar.\n'
'Built-In Templates¶\n'
'Many of the built-in templates '
'work better if you set certain '
'fields on your target or page '
"definitions. Here's a list of "
'those fields:\n'
'\n'
'\n'
'\n'
'Field\n'
'Description\n'
'\n'
'\n'
'\n'
'\n'
'prefix\n'
'The base path for this site. Use / '
'for a site served from the '
'top-level of its domain. Required '
'for navigation if your site has '
'subfolders or "pretty URLs".\n'
'\n'
'\n'
'logo\n'
'URL or path for a logo image to '
'use in the top-left. If not '
'defined, uses a text header '
'instead.\n'
'\n'
'\n'
'google_analytics_tag\n'
'String tag to use with Google '
'Analytics, e.g. "UA-00000000-0". '
"If not defined, doesn't load "
'Google Analytics.\n'
'\n'
'\n'
'repository\n'
"URL to this site's source "
'repository on GitHub. Required for '
'the "Edit on GitHub" button.\n'
'\n'
'\n'
'url\n'
'The fully-qualified URL for the '
'base of the site. Required by the '
'sitemap and Google Search '
'templates.\n'
'\n'
'\n'
'stylesheet\n'
'URL or path to the default '
'stylesheet. The default includes '
'Bootstrap 4.5 as well as custom '
'CSS for code tabs, callouts, and '
'the page layout. See the styles '
'dir for the source SCSS. The '
'default is served by dactyl.link.\n'
'\n'
'\n'
'dactyljs\n'
'URL or path to the Dactyl '
'JavaScript file to use. This '
'defines "jump to top" and code tab '
'behavior. The default is served by '
'dactyl.link.\n'
'\n'
'\n'
'bootstrapjs\n'
'URL or path to the Bootstrap '
'JavaScript file to use. The '
'default is served by '
'BootstrapCDN.\n'
'\n'
'\n'
'fontawesomecss\n'
'URL or path to FontAwesome (v4) '
'CSS file to use. The default is '
'served by BootstrapCDN.\n'
'\n'
'\n'
'\n'
'Page Templates¶\n'
'The following built-in templates '
'represent full pages, so you can '
'use them with the '
'default_template: and template: '
'settings in the config file or '
'frontmatter. You can also derive '
'your own templates from these '
'templates using {% extends '
"'template' %} syntax.\n"
'\n'
'\n'
'\n'
'Template\n'
'Description\n'
'\n'
'\n'
'\n'
'\n'
'404.html\n'
'Contains an error message intended '
'to be used as a custom 404 page.\n'
'\n'
'\n'
'base.html\n'
'A general purpose template with a '
'3-column layout, fixed header, and '
'a footer. The navigation uses the '
'hierarchy (parent and child) '
'fields introduced by Dactyl '
'v0.10.0. This uses Bootstrap '
'4.5.0. Most of the other built-in '
'templates are derived from this '
'template.\n'
'\n'
'\n'
'doc.html\n'
'Specialized for individual '
'documents. This is the new default '
'template. The right sidebar has an '
'in-page table of contents, and '
'this runs code tab and syntax '
'highlighting JavaScript by '
'default. (You still need to enable '
'the multicode_tabs filter in your '
'dactyl-config.yml file to get code '
'tab syntax.)\n'
'\n'
'\n'
'landing.html\n'
'A landing page that displays a '
'list of child pages in the center '
'column.\n'
'\n'
'\n'
'pdf-cover.html\n'
'A cover page and table of contents '
'for PDFs.\n'
'\n'
'\n'
'redirect.html\n'
'Redirects the user to another URL, '
"as set by the page's redirect_url "
'field. Useful for deprecating '
'pages.\n'
'\n'
'\n'
'simple.html\n'
'A minimal template with no '
'dependencies.\n'
'\n'
'\n'
'template-sitemap.txt\n'
'A template for a text sitemap for '
'use by search engines.\n'
'\n'
'\n'
'\n'
'When extending the default '
'templates, you many of them have '
'blocks you can replace. For the '
'full list, see the templates '
'directly.\n'
'Module Templates¶\n'
'The following built-in templates '
'are partial modules you can use '
'with {% include '
"'templatehere.html' %} blocks from "
'other templates. Many of these '
'pieces are used by the page '
'templates above, as well:\n'
'\n'
'\n'
'\n'
'Template\n'
'Description\n'
'\n'
'\n'
'\n'
'\n'
'algolia-docsearch.html\n'
'Provides a search box (and '
'accompanying resources) powered by '
'Algolia DocSearch. To use this, '
'you must provide your Algolia API '
"key in the target's "
'algolia_api_key field provide your '
"index name in the target's "
'algolia_index_name field.\n'
'\n'
'\n'
'breadcrumbs.html\n'
'Provides breadcrumbs to the '
'current page, based on the '
'hierarchy fields.\n'
'\n'
'\n'
'children.html\n'
'Displays a bulleted list of '
'children of the current page. You '
'can modify the behavior by setting '
'certain properties before '
'including this template. (See '
'below for an example.)\n'
'\n'
'\n'
'footer.html\n'
'A footer containing a copyright '
'notice, license link, and language '
'selector (if you have the right '
'fields defined).\n'
'\n'
'\n'
'github-edit.html\n'
'A button that links to edit the '
"current page's source file on "
"GitHub. Requires the target's "
'repository field to be the URL of '
"the site's repository on GitHub.\n"
'\n'
'\n'
'header.html\n'
'A fixed header containing a logo, '
'navigation to top-level pages, '
'search, and Edit on GitHub buttons '
'if the right fields are defined.\n'
'\n'
'\n'
'language-dropdown.html\n'
'A language-selector dropdown that '
'points to the equivalent page in '
'other languages, if you have '
'multiple languages defined. (This '
'is the one used in the header.)\n'
'\n'
'\n'
'language-dropdown.html\n'
'A horizontal language selector '
'that points to the equivalent page '
'in other languages, if you have '
'multiple languages defined. (This '
'is the one used in the footer.)\n'
'\n'
'\n'
'page-toc.html\n'
'A Bootstrap/ScrollSpy-ready table '
'of contents based on the headers '
"in the current page's Markdown "
'contents.\n'
'\n'
'\n'
'tree-nav.html\n'
'Tree-style site navigation with '
'collapsible levels. You can set a '
'custom page to be the "top" of the '
'tree to show only a subset of your '
'site. Otherwise it uses the first '
'page (usually the auto-provided '
'cover page) as the top of the '
'tree. Set nav_omit: true on a page '
'to hide that page from this '
'navigation.\n'
'\n'
'\n'
'\n'
'Children Module¶\n'
'The following demonstrates how to '
'use the children.html template to '
'display a list of children of a '
'page (including links):\n'
'{ % set parent_html = '
"'some-parent.html' %}\n"
'{ % set show_blurbs = True %}\n'
'{ % set depth = 3 %}\n'
"{ % include 'children.html' %}\n"
'\n'
'You can omit any or all of the {% '
'set ... %} statements to use the '
'defaults:\n'
'\n'
'\n'
'\n'
'Setting\n'
'Description\n'
'Default\n'
'\n'
'\n'
'\n'
'\n'
'parent_html\n'
"Which page's children to show. The "
'HTML filename of that page.\n'
'The current page.\n'
'\n'
'\n'
'show_blurbs\n'
"If True, add the child page's "
'blurb attribute next to its link.\n'
'False\n'
'\n'
'\n'
'depth\n'
'How many levels in the hierarchy '
'to show below the parent.\n'
'5\n'
'\n'
'\n'
'\n'
'Tree Nav Module¶\n'
'The following shows how to display '
'a subset of the tree nav (starting '
'with the file some_parent.html) '
'instead of the full tree:\n'
'{ % set tree_top = '
"pages|selectattr('html', "
"'defined_and_equalto', "
"'some_parent.html')|list|first %}\n"
"{ % include 'tree-nav.html' %}\n"
'\n'
'Template Data¶\n'
'Dactyl provides the following '
'information to templates, which '
"you can access with Jinja's "
'templating syntax (e.g. {{ '
'target.display_name }}):\n'
'\n'
'\n'
'\n'
'Field\n'
'Value\n'
'\n'
'\n'
'\n'
'\n'
'target\n'
'The target definition of the '
'current target.\n'
'\n'
'\n'
'pages\n'
'The array of page definitions in '
'the current target. Use this to '
'generate navigation across pages. '
"(The default templates don't do "
'this, but you should.)\n'
'\n'
'\n'
'currentpage\n'
'The definition of the page '
'currently being rendered.\n'
'\n'
'\n'
'categories\n'
'A de-duplicated array of '
'categories that are used by at '
'least one page in this target, '
'sorted in the order they first '
'appear.\n'
'\n'
'\n'
'config\n'
'The global Dactyl config object.\n'
'\n'
'\n'
'content\n'
'The parsed HTML content of the '
'page currently being rendered.\n'
'\n'
'\n'
'current_time\n'
'The current date as of rendering. '
'The format is YYYY-MM-DD by '
'default; you can also set the '
'time_format field to a custom '
'stftime format string.\n'
'\n'
'\n'
'mode\n'
'The output format: either html '
'(default), pdf, or md.\n'
'\n'
'\n'
'page_toc\n'
'A table of contents generated from '
"the current page's headers. Wrap "
'this in a <ul> element.\n'
'\n'
'\n'
'sidebar_content\n'
'(Deprecated alias for page_toc.)\n'
'\n'
'\n',
'related_links': ['frontmatter.html',
'code-highlighting.html'],
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything'],
'template': 'template-extends.html'},
{'__dactyl_provided_filename__': True,
'blurb': 'This page demonstrates how you can use '
"Dactyl's built-in hierarchy features "
'to generate a table of contents '
'automatically.',
'category': 'Extending',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Hierarchy Demo¶': '#hierarchy-demo'},
'hover_anchors': '¶',
'html': 'hierarchy.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33aca0>,
'md': 'extending/hierarchy.md',
'name': 'Hierarchy Demo',
'parent': 'extending-index.html',
'plaintext': 'Hierarchy Demo¶\n'
'This page demonstrates how you can '
"use Dactyl's built-in hierarchy "
'features to generate a table of '
'contents automatically.\n'
'Source:\n'
'<ul>\n'
'{% macro page_w_children(pg) %}\n'
' <li class="dactyl-toc-entry"><a '
'href="{{ pg.html }}">{{ pg.name '
'}}</a></li>\n'
' {% if pg.children %}\n'
' <ul>\n'
' {% for child in pg.children '
'%}\n'
' {{ page_w_children(child) '
'}}\n'
' {% endfor %}\n'
' </ul>\n'
' {% endif %}\n'
'{% endmacro %}\n'
'\n'
'{% for page in pages %}\n'
' {% if page.parent is undefined '
'%}\n'
' {{ page_w_children(page) }}\n'
' {% endif %}\n'
'{% endfor %}\n'
'</ul>\n'
'\n'
'Results:',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything'],
'template': 'template-hierarchy.html'},
{'blurb': 'This page demonstrates custom filters '
'in Dactyl. In "Metal Gear Solid 2", '
'the la-li-lu-le-lo are an organization '
'who brainwash people to say '
'"la-li-lu-le-lo" instead of '
'"la-li-lu-le-lo" when speaking aloud, '
'even among their compatriots.',
'category': 'Extending',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers', 'patriots'],
'foo': 'fooooooo',
'headermap': {'Custom Filter¶': '#custom-filter'},
'hover_anchors': '¶',
'html': 'filter-examples-patriots.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33ad30>,
'md': 'extending/patriots.md',
'name': 'Custom Filter',
'parent': 'extending-index.html',
'plaintext': 'Custom Filter¶\n'
'This page demonstrates custom '
'filters in Dactyl. In "Metal Gear '
'Solid 2", the la-li-lu-le-lo are '
'an organization who brainwash '
'people to say "la-li-lu-le-lo" '
'instead of "la-li-lu-le-lo" when '
'speaking aloud, even among their '
'compatriots.\n'
'This page should read normally in '
'the markdown source, but in the '
'Dactyl output if the patriots '
'filter is enabled, all instances '
"of the la-li-lu-le-lo' name is "
'replaced with la-li-lu-le-lo.\n'
'If a custom filter name is '
'satisfied by multiple custom '
'filter directories, or by a custom '
'filter and by a Dactyl built-in '
'filter, the first listed custom '
'filter directory takes highest '
'preference, and the Dactyl '
'built-in filters are lowest '
'preference. However, if importing '
'a filter fails (for example, due '
'to a syntax error), a '
'lower-precedence filter with the '
'same name may be loaded instead.',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'blurb': 'This page demonstrates custom filters '
'in Dactyl. In "Metal Gear Solid 2", '
'the La-Li-Lu-Le-Lo are an organization '
'who brainwash people to say '
'"la-li-lu-le-lo" instead of '
'"La-Li-Lu-Le-Lo" when speaking aloud, '
'even among their comla-li-lu-le-lo.',
'category': 'Extending',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers', 'patriots2'],
'foo': 'fooooooo',
'headermap': {'Custom Filter¶': '#custom-filter'},
'hover_anchors': '¶',
'html': 'filter-examples-patriots2.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33adc0>,
'md': 'extending/patriots.md',
'name': 'Custom Filter 2',
'parent': 'extending-index.html',
'plaintext': 'Custom Filter¶\n'
'This page demonstrates custom '
'filters in Dactyl. In "Metal Gear '
'Solid 2", the La-Li-Lu-Le-Lo are '
'an organization who brainwash '
'people to say "la-li-lu-le-lo" '
'instead of "La-Li-Lu-Le-Lo" when '
'speaking aloud, even among their '
'comla-li-lu-le-lo.\n'
'This page should read normally in '
'the markdown source, but in the '
'Dactyl output if the '
'la-li-lu-le-lo filter is enabled, '
'all instances of the '
"La-Li-Lu-Le-Lo' name is replaced "
'with la-li-lu-le-lo.\n'
'If a custom filter name is '
'satisfied by multiple custom '
'filter directories, or by a custom '
'filter and by a Dactyl built-in '
'filter, the first listed custom '
'filter directory takes highest '
'preference, and the Dactyl '
'built-in filters are lowest '
'preference. However, if importing '
'a filter fails (for example, due '
'to a syntax error), a '
'lower-precedence filter with the '
'same name may be loaded instead.',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'__dactyl_provided_filename__': True,
'blurb': 'The include_code filter provides a '
'function that can make a code sample '
'from a file, pulling in just specific '
'lines if desired.',
'category': 'Extending',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers', 'include_code'],
'foo': 'fooooooo',
'headermap': {'Code Includer¶': '#code-includer'},
'hover_anchors': '¶',
'html': 'include_code.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33ae50>,
'md': 'extending/include_code.md',
'name': 'Code Includer',
'parent': 'extending-index.html',
'plaintext': 'Code Includer¶\n'
'The include_code filter provides a '
'function that can make a code '
'sample from a file, pulling in '
'just specific lines if desired.\n'
'Call it like so:\n'
'{{ '
'include_code("sample_include.json", '
'lines="1,3,5-6", '
'mark_disjoint=True) }}\n'
'\n'
'Sample:\n'
'{"line one": "here",\n'
'...\n'
'"third line": 3,\n'
'...\n'
' "line 5": "FIVE",\n'
'"six": 6\n'
'\n'
'One range:\n'
'"second line": true,\n'
'"third line": 3,\n'
' "4th line": [1,2,3,4],\n'
'\n'
'The whole file:\n'
'{"line one": "here",\n'
'"second line": true,\n'
'"third line": 3,\n'
' "4th line": [1,2,3,4],\n'
' "line 5": "FIVE",\n'
'"six": 6\n'
'}\n'
'\n'
'Custom separator string for '
'disjoint lines:\n'
'{"line one": "here",\n'
'"second line": true,\n'
'... (line omitted)...\n'
' "4th line": [1,2,3,4],\n'
' "line 5": "FIVE",\n'
'"six": 6\n'
'}\n',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'category': 'Extending',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'hover_anchors': '¶',
'html': 'debug.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33aee0>,
'md': 'extending/debug.md',
'name': 'Debug',
'no_highlighting': True,
'parent': 'extending-index.html',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything'],
'template': 'template-minimal.html'}],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Extending Dactyl¶': '#extending-dactyl'},
'hover_anchors': '¶',
'html': 'extending-index.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33ab80>,
'md': 'extending/index.md',
'name': 'Extending Dactyl',
'parent': 'index.html',
'plaintext': 'Extending Dactyl¶\n'
'Dactyl is designed to be customized and extended '
"to each individual project's needs. These pages "
'demonstrate some ways you can extend Dactyl.',
'section_header': True,
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything'],
'template': 'landing.html'}],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Dactyl¶': '#dactyl', 'Installation¶': '#installation'},
'hover_anchors': '¶',
'html': 'index.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d336ca0>,
'md': 'index.md',
'name': 'Index',
'pdf_template': 'pdf-cover.html',
'plaintext': 'Dactyl¶\n'
'Documentation tools for enterprise-quality documentation from '
'Markdown source. Dactyl has advanced features to enable '
'single-sourcing and an extensible syntax for building '
'well-organized, visually attractive docs. It generates output '
'in HTML (natively), and can make PDFs if you have Prince '
'installed.\n'
'Installation¶\n'
'Dactyl requires Python 3. Install with pip:\n'
'sudo pip3 install dactyl\n'
'\n'
'Or a local install in a virtualenv:\n'
'# Create an activate a virtualenv so the package and '
'dependencies are localized\n'
'virtualenv -p `which python3` venv_dactyl\n'
'source venv_dactyl/bin/activate\n'
'pip3 install dactyl\n',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything'],
'template': 'landing.html'},
{'__dactyl_provided_filename__': True,
'blurb': 'Dactyl is intended to be used with a config file (typically '
'dactyl-config.yml) that specifies a full list of files to build '
"with necessary metadata and other config. So, if you've got this "
'set up, you can run Dactyl like this:',
'children': [{'__dactyl_provided_filename__': True,
'blurb': 'Dactyl is intended to be used with a config file '
'containing a list of pages to parse. Pages are '
'grouped into "targets" that represent a group of '
'documents to be built together; a page can belong to '
'multiple targets, and can even contain conditional '
'syntax so that it builds differently depending on '
'the target in question. Targets and pages can also '
'use different templates from each other, and pages '
'can inherit semi-arbitrary key/value pairs from the '
'targets.',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Configuration¶': '#configuration',
'Directory Paths¶': '#directory-paths',
'Pages¶': '#pages',
'Targets¶': '#targets'},
'hover_anchors': '¶',
'html': 'config.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d336dc0>,
'md': 'usage/config.md',
'name': 'Configuration',
'parent': 'usage.html',
'plaintext': 'Configuration¶\n'
'Dactyl is intended to be used with a config file '
'containing a list of pages to parse. Pages are '
'grouped into "targets" that represent a group of '
'documents to be built together; a page can '
'belong to multiple targets, and can even contain '
'conditional syntax so that it builds differently '
'depending on the target in question. Targets and '
'pages can also use different templates from each '
'other, and pages can inherit semi-arbitrary '
'key/value pairs from the targets.\n'
'The input pages in the config file should be '
'specified relative to the content_path, which is '
'content/ by default. You can also specify a URL '
'to pull in a Markdown file from a remote source, '
"but if you do, Dactyl won't run any "
'pre-processing on it.\n'
'Directory Paths¶\n'
'An advanced setup would probably have a '
'directory structure such as the following:\n'
'./ # Top-level dir; this is '
'where you run dactyl_*\n'
'./dactyl-config.yml # Default config file '
'name\n'
'./content # Dir containing your '
'.md source files\n'
'---------/*/*.md # You can sort .md files '
'into subdirs if you like\n'
'---------/static/* # Static images '
'referencd in your .md files\n'
'./templates/template-*.html # Custom HTML '
'Templates\n'
'./assets # Directory for static '
'files referenced by templates\n'
'./out # Directory where output '
'gets generated. Can be deleted\n'
'\n'
'All of these paths can be configured.\n'
'Targets¶\n'
'A target represents a group of pages, which can '
'be built together or concatenated into a single '
'PDF. You should have at least one target defined '
'in the targets array of your Dactyl config file. '
'A target definition should consist of a short '
'name (used to specify the target in the '
'commandline and elsewhere in the config file) '
'and a human-readable display_name (used mostly '
'by templates but also when listing targets on '
'the commandline).\n'
'A simple target definition:\n'
'targets:\n'
' - name: kc-rt-faq\n'
' display_name: Ripple Trade Migration '
'FAQ\n'
'\n'
'In addition to name and display_name, a target '
'definition can contain arbitrary key-values to '
'be inherited by all pages in this target. '
'Dictionary values are inherited such that keys '
"that aren't set in the page are carried over "
'from the target, recursively. The rest of the '
'time, fields that appear in a page definition '
'take precedence over fields that appear in a '
'target definition.\n'
'Some things you may want to set at the target '
'level include filters (an array of filters to '
'apply to pages in this target), template '
'(template to use when building HTML), and '
'pdf_template (template to use when building '
'PDF). You can also use the custom values in '
'templates and preprocessing. Some filters define '
"additional fields that affect the filter's "
'behavior.\n'
'The following field names cannot be inherited: '
'name, display_name, and pages.\n'
'Pages¶\n'
'Each page represents one HTML file in your '
'output. A page can belong to one or more '
'targets. When building a target, all the pages '
'belonging to that target are built in the order '
'they appear in the pages array of your Dactyl '
'config file.\n'
'Example of a pages definition with two files:\n'
'pages:\n'
' - name: RippleAPI\n'
' category: References\n'
' html: reference-rippleapi.html\n'
' md: '
'https://raw.githubusercontent.com/ripple/ripple-lib/0.17.2/docs/index.md\n'
' filters:\n'
' - remove_doctoc\n'
' - add_version\n'
' targets:\n'
' - local\n'
' - ripple.com\n'
'\n'
' - name: rippled\n'
' category: References\n'
' html: reference-rippled.html\n'
' md: reference-rippled.md\n'
' targets:\n'
' - local\n'
' - ripple.com\n'
'\n'
'Each individual page definition can have the '
'following fields:\n'
'\n'
'\n'
'\n'
'Field\n'
'Type\n'
'Description\n'
'\n'
'\n'
'\n'
'\n'
'targets\n'
'Array\n'
'The short names of the targets that should '
'include this page.\n'
'\n'
'\n'
'html\n'
'String\n'
'(Optional) The filename where this file should '
'be written in the output directory. If omitted, '
'Dactyl chooses a filename based on the md field '
'(if provided), the name field (if provided), or '
'the current time (as a last resort). By default, '
'generated filenames flatten the folder structure '
'of the md files. To instead replicate the folder '
'structure of the source documents in '
'auto-generated filenames, add '
'flatten_default_html_paths: true to the top '
'level of your Dactyl config file.\n'
'\n'
'\n'
'name\n'
'String\n'
'(Optional) Human-readable display name for this '
'page. If omitted but md is provided, Dactyl '
'tries to guess the right file name by looking at '
'the first two lines of the md source file.\n'
'\n'
'\n'
'md\n'
'String\n'
'(Optional) The markdown filename to parse to '
'generate this page, relative to the content_path '
'in your config. If this is not provided, the '
'source file is assumed to be empty. (You might '
'do that if you use a nonstandard template for '
'this page.)\n'
'\n'
'\n'
'openapi_specification\n'
'String\n'
'(Optional) The file path or http(s) URL to an '
'OpenAPI v3.0 specification to be parsed into '
'generated documentation. If provided, this entry '
'becomes expanded into a set of several pages '
'that describe the methods and data types defined '
'for the given API. The generated pages inherit '
'the other fields of this page object. '
'Experimental. If the path is a relative path, it '
'is evaluated based on the directory Dactyl is '
'called from, not the content directory.\n'
'\n'
'\n'
'api_slug\n'
'String\n'
'(Optional) If this is an openapi_specification '
'entry,\n'
'\n'
'\n'
'category\n'
'String\n'
'(Optional) The name of a category to group this '
"page into. This is used by Dactyl's built-in "
'templates to organize the table of contents.\n'
'\n'
'\n'
'template\n'
'String\n'
'(Optional) The filename of a custom Jinja HTML '
'template to use when building this page for '
'HTML, relative to the template_path in your '
'config.\n'
'\n'
'\n'
'pdf_template\n'
'String\n'
'(Optional) The filename of a custom Jinja HTML '
'template to use when building this page for PDF, '
'relative to the template_path in your config.\n'
'\n'
'\n'
'openapi_md_template_path\n'
'String\n'
'(Optional) Path to a folder containing templates '
'to be used for OpenAPI spec parsing. If omitted, '
'use the built-in templates.\n'
'\n'
'\n'
'parent\n'
'String\n'
'(Optional) The HTML filename of the page to '
'treat as a parent of this one for purposes of '
'hierarchy. If omitted, treat the page as a '
'"top-level" page.\n'
'\n'
'\n'
'...\n'
'(Various)\n'
'Additional arbitrary key-value pairs as desired. '
'These values can be used by templates or '
'pre-processing.\n'
'\n'
'\n'
'\n'
'If the file specified by md begins with YAML '
'frontmatter, separated by a line of exactly ---, '
'the frontmatter is used as a basis for these '
'fields. Certain frontmatter fields are adapted '
'from Jekyll format to Dactyl format: for '
'example, title gets copied to name if the page '
'does not have a name.\n'
'The following fields are automatically added '
"after a page has been parsed to HTML. (They're "
'not available when preprocessing or rendering '
'Markdown to HTML, but are available when '
'rendering HTML templates.)\n'
'\n'
'\n'
'\n'
'Field\n'
'Type\n'
'Description\n'
'\n'
'\n'
'\n'
'\n'
'plaintext\n'
'String\n'
"A plaintext-only version of the page's markdown "
'content, with all Markdown and HTML syntax '
'removed.\n'
'\n'
'\n'
'headermap\n'
'Dictionary\n'
"A mapping of the page's headers to the unique "
'IDs of those headers in the generated HTML '
'version.\n'
'\n'
'\n'
'blurb\n'
'String\n'
"An introductory blurb generated from the page's "
'first paragraph of text.\n'
'\n'
'\n'
'children\n'
'List\n'
'A list of pages, in order of appearance, that '
'refer to this page as their parent. Each of '
'these "child" pages is a reference to the page '
'definition (dictionary) for that child.\n'
'\n'
'\n'
'is_ancestor_of\n'
'Function\n'
'A function that takes one argument, the string '
'identifying a potential child page by that '
"child's html field. This function returns True "
'if this page is a direct or indirect parent of '
'the child page.\n'
'\n'
'\n',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'__dactyl_provided_filename__': True,
'blurb': 'Dactyl includes a link-checking script to '
'automatically detect and report on broken hyperlinks '
'in your generated documentation.',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Link Checking¶': '#link-checking',
'Unusual Link Types¶': '#unusual-link-types',
'Usage¶': '#usage'},
'hover_anchors': '¶',
'html': 'link-checking.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d336e50>,
'md': 'usage/link-checking.md',
'name': 'Link Checking',
'parent': 'usage.html',
'plaintext': 'Link Checking¶\n'
'Dactyl includes a link-checking script to '
'automatically detect and report on broken '
'hyperlinks in your generated documentation.\n'
'Usage¶\n'
'First, build some documentation to an output '
'path. Depending on your configuration, you may '
'want to build multiple targets to different '
'output directories before running the link '
'checker.\n'
'Then, run the link checker as follows:\n'
'$ dactyl_link_checker\n'
'\n'
'This checks all the files in the output '
'directory for links and confirms that any '
'HTTP(S) links, including relative links to other '
'files, are valid. For anchor links, it checks '
'that an element with the correct ID exists in '
'the target file. It also checks that the src of '
'all image tags exists.\n'
'If there are links that are always reported as '
"broken but you don't want to remove (for "
"example, URLs that block Python's user-agent) "
'you can add them to the known_broken_links array '
'in the config.\n'
'In quiet mode (-q), the link checker still '
'reports in every 30 seconds just so that it '
"doesn't get treated as stalled and killed by "
'continuous integration software (e.g. Jenkins).\n'
'To reduce the number of meaningless failure '
'reports (because a particular website happened '
'to be down momentarily while you ran the link '
'checker), if there are any broken remote links, '
'the link checker waits 2 minutes after finishing '
'and then retries those links in case they came '
"back up. (If they did, they're not considered "
"broken for the link checker's final report.)\n"
'You can also run the link checker in offline '
'mode (-o) to skip any remote links and just '
'check that the files and anchors referenced '
'exist in the output directory.\n'
'If you have a page that uses JavaScript or '
'something to generate anchors dynamically, the '
"link checker can't find those anchors (since it "
"doesn't run any JS). You can add such pages to "
'the ignore_anchors_in array in your config to '
'skip checking for links that go to anchors in '
'such pages.\n'
'Unusual Link Types¶\n'
'Some unusual types of links that you may '
'encounter in HTML or Markdown include:\n'
'\n'
'Protocol relative URL - these start with // and '
'refer to "whatever protocl is being used now". '
'Dactyl assumes HTTPS should work for these '
'URLs.\n'
'Mailto URL - Email addresses. The link checker '
'ignores these and other links that use other URI '
'schemes.\n'
'Javascript Bookmarklet - JavaScript code '
'embedded in the href directly with javascript:. '
'The link checker ignores these.\n'
'Empty anchor - A link to #. This type of link is '
'often used to trigger JavaScript events. The '
'link checker considers these invalid for <img> '
'paths but OK for <a> tags.\n',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'__dactyl_provided_filename__': True,
'blurb': 'The style checker is experimental. It is only '
'suitable for English text. It reports several '
'details about document contents that may be helpful '
'for identifying documents whose readability you '
'could improve. These details are:',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Discouraged Words and Phrases¶': '#discouraged-words-and-phrases',
'Length Metrics¶': '#length-metrics',
'Readability Goals¶': '#readability-goals',
'Readability Scores¶': '#readability-scores',
'Spell Checking¶': '#spell-checking',
'Style Checking¶': '#style-checking'},
'hover_anchors': '¶',
'html': 'style-checking.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d336ee0>,
'md': 'usage/style-checking.md',
'name': 'Style Checking',
'parent': 'usage.html',
'plaintext': 'Style Checking¶\n'
'The style checker is experimental. It is only '
'suitable for English text. It reports several '
'details about document contents that may be '
'helpful for identifying documents whose '
'readability you could improve. These details '
'are:\n'
'\n'
'Discouraged words and phrases.\n'
'Page length details.\n'
'Readability scores.\n'
'Spell-checking.\n'
'\n'
'Example usage:\n'
'$ dactyl_style_checker\n'
'\n'
'The style checker re-generates contents '
'in-memory (never writing it out), unlike the '
'link checker which requires you to run '
'dactyl_build first. It only checks contents that '
'come from Markdown, not from HTML templates.\n'
'The style checker uses the first target in the '
'config file unless you specify another target '
'with -t. You can check just one file by passing '
'its HTML path in the --only parameter.\n'
'The exit code of the command is 0 (success) if '
'it found no discouraged words, the spell checker '
'found no unknown words, and no pages failed '
'their configured readability goals. Otherwise, '
'the exit code of the command is 1 (failure).\n'
'Discouraged Words and Phrases¶\n'
'You can suggest specific words or phrases to '
'discourage. The style checker checks for '
'instances of these words and phrases in '
"documents' content, and suggests alternatives "
'based on the phrase file. Dactyl does not check '
'text in <code>, <pre>, and <tt> elements since '
'those are intended to be code samples.\n'
'To configure lists of discouraged words and '
'phrases, add the following config options:\n'
'\n'
'\n'
'\n'
'Field\n'
'Value\n'
'Description\n'
'\n'
'\n'
'\n'
'\n'
'word_substitutions_file\n'
'String\n'
'The path to a YAML file with a single top-level '
'map. The keys are the words to discourage and '
'the values are suggestions of words to replace '
'them with.\n'
'\n'
'\n'
'phrase_substitutions_file\n'
'String\n'
'The path to a YAML file with a single top-level '
'map. The keys are phrases to discourage and the '
'values are suggestions of phrases to replace '
'them with.\n'
'\n'
'\n'
'\n'
'You can add an exemption to a specific '
'discouraged word/phrase rule with an HTML '
'comment. The exemption applies to the whole '
'output (HTML) file in which it appears.\n'
'Maybe the word "will" is a discouraged word, but '
'you really want to use it here without flagging '
'it as a violation? Adding a comment like this '
'<!-- STYLE_OVERRIDE: will --> makes it so.\n'
'\n'
'Spell Checking¶\n'
'Dactyl uses pyspellchecker to report possible '
'spelling errors and suggest corrections. The '
'built-in dictionary is not very thorough; you '
'can extend it by providing a dictionary file '
'with more words. Spell checking is '
'case-insensitive.\n'
'If you want the spell checker to skip a page, '
'put skip_spell_checker: true in the page '
'definition.\n'
'If you want to ignore one or more words on a '
'single page only, add a comment such as the '
'following anywhere in the page:\n'
'<!-- IGNORE_SPELLING: affectednodes, '
'creatednode, deletednode, modifiednode -->\n'
'\n'
'To extend the built-in dictionary used for all '
'files, add the following field to the config. '
'(You cannot remove words from the built-in '
'dictionary.)\n'
'\n'
'\n'
'\n'
'Field\n'
'Value\n'
'Description\n'
'\n'
'\n'
'\n'
'\n'
'spelling_file\n'
'String\n'
'Path to a text file with words to add to the '
'dictionary. Each line of the file should contain '
'a single word (case-insensitive).\n'
'\n'
'\n'
'\n'
'Length Metrics¶\n'
'Dactyl reports the number of characters of text, '
'number of sentences, and number of words in each '
'document. These counts only include text '
'contents (the parts generated from Markdown). '
'They do not include code samples (not even '
'inlined code words), or images/figures. The '
'sentence counts are estimates. Headings, list '
'items, and table cells each count as one '
'sentence in these metrics. The summary includes '
'the averages across all pages, and the stats for '
'the three longest and shortest pages.\n'
'These metrics are intended to be helpful for '
'choosing documents that would be better off '
'combined or split up. They can also be useful '
'for interpreting readability scores, which tend '
'to be less reliable for very short documents.\n'
'Readability Scores¶\n'
'The style checker reports readability scores '
'based on several formulas implemented in the '
'textstat library. These can help you identify '
'documents with a high proportion of big words '
'and long sentences.\n'
'\n'
'Caution: Readability formulas are not very '
'smart. Trying to get a high readability score '
'can actually decrease the clarity of your '
"writing if you aren't mindful of other factors. "
"Things readability formulas usually don't take "
'into account include: brevity; complexity of the '
'high-level structure; logical connections such '
'as cause and effect; and precise use of '
'language. They tend to score tables and bulleted '
'lists badly even though those structure are very '
'helpful for actual readability.\n'
'\n'
'By default, Dactyl prints the readability scores '
'for each page as it analyzes them. The -q option '
'hides this output. The summary at the end lists '
'the average scores for all pages analyzed and '
'the three pages with the worst Flesch Reading '
'Ease scores.\n'
'Readability Goals¶\n'
'You can set readability goals for individual '
'pages or an entire target by adding the '
'readability_goals field. This field should '
'contain a map of readability metrics to target '
'scores. Goals defined for individual pages '
'override goals set for the entire target. Dactyl '
"compares a page's readability scores to any "
'goals set and reports a list of pages that '
'failed their goals in the summary. The goal '
"passes if the page's score is equal better "
'(easier to read) than the stated goal value, and '
'fails otherwise. For Flesch Reading Ease, higher '
'scores represent better readability; for the '
'other tests, lower scores represent better '
'readability.\n'
'Note: Since very short pages tend to have '
'inconsistent and unreliable readability scores, '
'Dactyl does not calculate readability scores for '
'pages with fewer than 10 "sentences". (Bullet '
'points, headings, and table cells each count as '
'separate "sentences" for this purpose.)\n'
'Example configuration:\n'
'targets:\n'
'\n'
' - name: my-target\n'
' display_name: Example Target\n'
' readability_goals:\n'
' flesch_reading_ease: 50\n'
' automated_readability_index: 12\n'
'\n'
'The available readability tests are:\n'
'\n'
'\n'
'\n'
'Field Name\n'
'Details\n'
'\n'
'\n'
'\n'
'\n'
'flesch_reading_ease\n'
'Flesch reading ease. Maximum score 121.22; no '
'limit on how negative the score can be.\n'
'\n'
'\n'
'smog_index\n'
'SMOG grade. Gives an estimated grade level.\n'
'\n'
'\n'
'coleman_liau_index\n'
'Coleman-Liau index. Gives an estimated grade '
'level.\n'
'\n'
'\n'
'automated_readability_index\n'
'Automated readability index. Gives an estimated '
'grade level.\n'
'\n'
'\n'
'dale_chall_readability_score\n'
'Dale-Chall readability formula. Decimal '
'representing difficulty; lower values map to '
'lower grade levels.\n'
'\n'
'\n'
'linsear_write_formula\n'
'Linsear Write formula. Gives an estimated grade '
'level.\n'
'\n'
'\n'
'gunning_fog\n'
'Gunning fog index. Gives an estimated grade '
'level.\n'
'\n'
'\n'
'\n'
'Estimated grade levels are based on the United '
'States school system and are given as decimal '
'approximations. For example, 11.5 represents '
'somewhere between 11th and 12th grade (high '
'school junior to senior).',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'blurb': 'Dactyl has the ability to build JSON formatted for '
'upload to ElasticSearch and even upload it directly.',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'ElasticSearch Compatibility¶': '#elasticsearch-compatibility',
'ElasticSearch JSON Templates¶': '#elasticsearch-json-templates'},
'hover_anchors': '¶',
'html': 'elasticsearch.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d336f70>,
'md': 'usage/elasticsearch.md',
'name': 'ElasticSearch Compatibility',
'parent': 'usage.html',
'plaintext': 'ElasticSearch Compatibility¶\n'
'Dactyl has the ability to build JSON formatted '
'for upload to ElasticSearch and even upload it '
'directly.\n'
'To build JSON files for upload to ElasticSearch, '
'use the --es mode:\n'
'dactyl_build --es\n'
'\n'
'This writes files to the usual output directory '
'using an ElasticSearch JSON template. Dactyl '
'skips any files that do not have a md source '
'parameter in this mode. The output filenames are '
"the pages' html filenames, except ending in "
'.json instead of .html. You can specify a custom '
'template for these JSON files using the '
'top-level default_es_template field in the '
'config file. This template must be a valid JSON '
'file and has several special properties as '
'described in ElasticSearch JSON Templates.\n'
'Dactyl can also upload these files directly to '
'an ElasticSearch instance, even when building '
'for another mode. For example, to build the HTML '
'version of a target named filterdemos but also '
"upload that target's JSON-formatted data to an "
'ElasticSearch instance:\n'
'dactyl_build -t filterdemos --html --es_upload '
'https://my-es-instance.example.com:9200\n'
'\n'
'The parameter to --es_upload should be the base '
'URL of your ElasticSearch index. You can omit '
'the parameter to use the default base URL of '
'http://localhost:9200.\n'
'ElasticSearch JSON Templates¶\n'
'Dactyl has a special format for JSON templates '
'meant for creating ElasticSearch data. These '
'templates must be valid JSON and are processed '
'according to the following rules:\n'
'\n'
"Any strings in the fields' values are "
'"preprocessed" in a similar context to the '
'Jinja2-based Markdown preprocessor. For example, '
'the string ElasticSearch Compatibility evaluates '
"to the page's name.\n"
'Any object containing the key __dactyl_eval__ is '
'evaluated as a Python expression. The object is '
'replaced with the results of the expression, '
'with lists becoming JSON arrays and dictionaries '
'becoming JSON objects.\n'
'The above rules apply recursively to values '
'nested in arrays and objects. All other values '
'are preserved literally.\n'
'\n'
'The context provided to the preprocessing and to '
'the __dactyl_eval__ expressions is the same and '
'contains the following:\n'
'\n'
'\n'
'\n'
'Field\n'
'Python Type\n'
'Description\n'
'\n'
'\n'
'\n'
'\n'
'currentpage\n'
'dict\n'
'The current page definition (usually derived '
'from the config file)\n'
'\n'
'\n'
'target\n'
'dict\n'
'The current target definition (usually derived '
'from the config file)\n'
'\n'
'\n'
'categories\n'
'list\n'
'A list of unique category values used by pages '
'in the current target, in order of appearance.\n'
'\n'
'\n'
'page_filters\n'
'list\n'
'A list of the names of Dactyl filters applied to '
'the current page.\n'
'\n'
'\n'
'mode\n'
'str\n'
'Always equal to es in this context\n'
'\n'
'\n'
'current_time\n'
'str\n'
'The current time, in the time_format specified '
'in the config. (Defaults to YYYY-MM-DD)\n'
'\n'
'\n'
'bypass_errors\n'
'bool\n'
'If true, this build is running with the option '
'to continue through errors where possible.\n'
'\n'
'\n',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'__dactyl_provided_filename__': True,
'blurb': 'Dactyl can parse an OpenAPI v3.0 specification to '
'generate API documentation for the API that '
'specification describes, including API methods and '
'object schemas.',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Ad-Hoc Usage¶': '#ad-hoc-usage',
'Config File¶': '#config-file',
'Custom Templates¶': '#custom-templates',
'OpenAPI Specifications¶': '#openapi-specifications'},
'hover_anchors': '¶',
'html': 'openapi.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a040>,
'md': 'usage/openapi.md',
'name': 'OpenAPI Specifications',
'parent': 'usage.html',
'plaintext': 'OpenAPI Specifications¶\n'
'Dactyl can parse an OpenAPI v3.0 specification '
'to generate API documentation for the API that '
'specification describes, including API methods '
'and object schemas.\n'
'Ad-Hoc Usage¶\n'
'You can use the --openapi <specfile> parameter '
'to build a single target from\n'
'dactyl_build --openapi openapi.yaml\n'
'\n'
'You can combine this with --md or --pdf to '
'output the generated documentation in Markdown '
'or PDF format, respectively.\n'
'Config File¶\n'
'You can add a special entry to the pages array '
'to represent an API reference; Dactyl will '
'expand that file into multiple pages that each '
'inherit any fields of this entry. For example:\n'
'- openapi_specification: '
'https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml\n'
' api_slug: petstore\n'
' foo: bar\n'
' targets:\n'
' - baz\n'
'\n'
'The api_slug field is optional, and provides a '
'prefix that gets used for a bunch of file names '
'and stuff. You can use the other fields to '
'specify which HTML templates to use or to pass '
'more info to those templates to control how they '
'display.\n'
'The generated pages are:\n'
'\n'
'An "All Methods" table of contents, listing '
'every path operation in the paths of the OpenAPI '
'specification.\n'
'"Tag Methods" table of contents pages for each '
'tag used in the OpenAPI specification.\n'
'Pages for all "API Methods" (path operations) in '
'paths of the OpenAPI specification.\n'
'A "Data Types" table of contents, listing every '
'data type defined in the schema section of the '
'OpenAPI specification.\n'
'Individual pages for each data type in the '
"OpenAPI specification's schema section.\n"
'\n'
'Custom Templates¶\n'
'You can override the templates used for '
'generated OpenAPI pages to adjust how the '
'Markdown is generated.\n'
'In the page or target definition of your config '
'file, set the openapi_md_template_path field to '
'a path that contains the following templates:\n'
'\n'
'\n'
'\n'
'Filename\n'
'Template for...\n'
'\n'
'\n'
'\n'
'\n'
'template-openapi_data_type.md\n'
"Each individual data type in the spec's schema "
'section.\n'
'\n'
'\n'
'template-openapi_data_types_toc.md\n'
'Table of contents for the data types.\n'
'\n'
'\n'
'template-openapi_endpoint_tag_toc.md\n'
'Table of contents for each endpoint tag in the '
'spec.\n'
'\n'
'\n'
'template-openapi_endpoint_toc.md\n'
'Table of contents for all endpoints and tags.\n'
'\n'
'\n'
'template-openapi_endpoint.md\n'
'Table of contents for each individual endpoint '
'in the paths section.\n'
'\n'
'\n'
'\n'
'These templates use Jinja syntax.',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']}],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Ad-Hoc Usage¶': '#ad-hoc-usage',
'Building Markdown¶': '#building-markdown',
'Building Only One Page¶': '#building-only-one-page',
'Building PDF¶': '#building-pdf',
'Listing Available Targets¶': '#listing-available-targets',
'Specifying a Config File¶': '#specifying-a-config-file',
'Specifying a Target¶': '#specifying-a-target',
'Static Files¶': '#static-files',
'Usage¶': '#usage',
'Watch Mode¶': '#watch-mode'},
'hover_anchors': '¶',
'html': 'usage.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d336d30>,
'md': 'usage/usage.md',
'name': 'Usage',
'parent': 'index.html',
'plaintext': 'Usage¶\n'
'Dactyl is intended to be used with a config file (typically '
'dactyl-config.yml) that specifies a full list of files to '
"build with necessary metadata and other config. So, if you've "
'got this set up, you can run Dactyl like this:\n'
'dactyl_build\n'
'\n'
'By default, this outputs HTML. You can also build a PDF or '
"even Markdown. For a full list of Dactyl's commandline "
'options, use the -h parameter.\n'
'Ad-Hoc Usage¶\n'
'Simple ("Ad-Hoc") usage:\n'
'$ dactyl_build --pages input1.md input2.md\n'
'\n'
'By default, the resulting HTML pages are written to a folder '
'called out/ in the current working directory. You can specify '
'a different output path in the config file or by using the -o '
'parameter.\n'
'Building PDF¶\n'
'Dactyl generates PDFs by making temporary HTML files and '
'running Prince. Use the --pdf command to generate a PDF. '
'Dactyl tries to come up with a sensible output filename by '
'default, or you can provide one (which must end in .pdf):\n'
'$ dactyl_build --pages input1.md input2.md --pdf MyGuide.pdf\n'
'\n'
'Specifying a Config File¶\n'
'By default, Dactyl looks for a config file named '
'dactyl-config.yml in the current working directory. You can '
'specify an alternate config file with the -c or --config '
'parameter:\n'
'$ dactyl_build -c path/to/alt-config.yml\n'
'\n'
'For more information on configuration, see Configuration and '
'the examples folder.\n'
'Specifying a Target¶\n'
'If your config file contains more than one target, Dactyl '
'builds the first one by default. You can specify a different '
'target by passing its name value with the -t parameter:\n'
'$ dactyl_build -t non-default-target\n'
'\n'
'Static Files¶\n'
'Your templates may require certain static files (such as '
'JavaScript, CSS, and images) to display properly. Your content '
'may have its own static files (such as diagrams and figures). '
'By default, Dactyl assumes that templates have static files in '
'the assets/ folder. You can configure this path and also '
'specify one or more paths to static files referenced by your '
'content. When you build, Dactyl copies files from these '
'folders to the output folder by default depending on which '
"mode you're building:\n"
'\n'
'\n'
'\n'
'Build Mode\n'
'Files copied to output folder by default\n'
'\n'
'\n'
'\n'
'\n'
'HTML\n'
'Both template and content static files\n'
'\n'
'\n'
'PDF\n'
'Neither template nor content static files (cannot be '
'overridden)\n'
'\n'
'\n'
'Markdown\n'
'Content static files only\n'
'\n'
'\n'
'ElasticSearch JSON\n'
'Neither template nor content static files\n'
'\n'
'\n'
'\n'
'You can use a commandline flag to explicitly specify what gets '
'copied to the output folder, except in the case of PDF. (In '
'PDF mode, Dactyl writes only the final PDF to the output '
'folder.) The flags are as follows:\n'
'\n'
'\n'
'\n'
'Flag (long version)\n'
'Short version\n'
'Meaning\n'
'\n'
'\n'
'\n'
'\n'
'--copy_static\n'
'-s\n'
'Copy all static files to the out dir.\n'
'\n'
'\n'
'--no_static\n'
'-S\n'
"Don't copy any static files to the out dir.\n"
'\n'
'\n'
'--template_static\n'
'-T\n'
"Copy only templates' static files to the out dir\n"
'\n'
'\n'
'--content_static\n'
'-C\n'
"Copy only the content's static files to the out dir\n"
'\n'
'\n'
'\n'
'The following config file parameters control what paths Dactyl '
'checks for static content:\n'
'\n'
'\n'
'\n'
'Field\n'
'Default\n'
'Description\n'
'\n'
'\n'
'\n'
'\n'
'template_static_path\n'
'assets/\n'
'Static files belonging to the templates.\n'
'\n'
'\n'
'content_static_path\n'
'(None)\n'
'Static files belonging to content. This can be a single folder '
'path, as a string, or an array of paths to files or folders. '
'Dactyl copies all files and folders (regardless of whether the '
'current target uses them).\n'
'\n'
'\n'
'\n'
'Listing Available Targets¶\n'
'If you have a lot of targets, it can be hard to remember what '
'the short names for each are. If you provide the -l flag, '
'Dactyl will list available targets and then quit without doing '
'anything:\n'
'$ dactyl_build -l\n'
'tests Dactyl Test Suite\n'
'rc-install Ripple Connect v2.6.3 Installation Guide\n'
'rc-release-notes \n'
'kc-rt-faq Ripple Trade Migration FAQ\n'
'\n'
'Building Markdown¶\n'
'This mode runs the pre-processor only, so you can generate '
'Markdown files that are more likely to display properly in '
'conventional Markdown parsers (like the one built into '
'GitHub). Use the --md flag to output Markdown files, skipping '
'the HTML/PDF templates entirely.\n'
'$ dactyl_build --md\n'
'\n'
'Building Only One Page¶\n'
'If you only want to build a single page, you can use the '
'--only flag, followed by the filename you want to build '
'(either the input filename ending in .md or the output '
'filename ending in .html):\n'
'dactyl_build --only index.html --pdf\n'
'\n'
'This command can be combined with the --pdf or --md flags. You '
'can also use it with the --target setting (in case you want '
"the context from the target even though you're only building "
'one page.)\n'
'Watch Mode¶\n'
'You can use the -w flag to make Dactyl run continuously, '
'watching for changes to its input templates or markdown files. '
'Whenever it detects that a file has changed, Dactyl '
'automatically rebuilds the output in whatever the current mode '
'is, (HTML, PDF, or Markdown).\n'
'To be detected as a change, the file has to match one of the '
'following patterns:\n'
'*.md\n'
'*/code_samples/*\n'
'template-*.html\n'
'\n'
'Beware: some configurations can lead to an infinite loop. (For '
'example, if your output directory is a subdirectory of your '
'content directory and you use Dactyl in --md mode.)\n'
'Limitations: Watch mode can be combined with --only, but '
're-builds the page even when it detects changes to unrelated '
"pages. Watch mode doesn't detect changes to the config file, "
'static files, or filters.\n'
'To stop watching, interrupt the Dactyl process (Ctrl-C in most '
'terminals).',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'__dactyl_provided_filename__': True,
'blurb': 'Dactyl is intended to be used with a config file containing a list '
'of pages to parse. Pages are grouped into "targets" that represent '
'a group of documents to be built together; a page can belong to '
'multiple targets, and can even contain conditional syntax so that '
'it builds differently depending on the target in question. Targets '
'and pages can also use different templates from each other, and '
'pages can inherit semi-arbitrary key/value pairs from the targets.',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Configuration¶': '#configuration',
'Directory Paths¶': '#directory-paths',
'Pages¶': '#pages',
'Targets¶': '#targets'},
'hover_anchors': '¶',
'html': 'config.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d336dc0>,
'md': 'usage/config.md',
'name': 'Configuration',
'parent': 'usage.html',
'plaintext': 'Configuration¶\n'
'Dactyl is intended to be used with a config file containing a '
'list of pages to parse. Pages are grouped into "targets" that '
'represent a group of documents to be built together; a page '
'can belong to multiple targets, and can even contain '
'conditional syntax so that it builds differently depending on '
'the target in question. Targets and pages can also use '
'different templates from each other, and pages can inherit '
'semi-arbitrary key/value pairs from the targets.\n'
'The input pages in the config file should be specified '
'relative to the content_path, which is content/ by default. '
'You can also specify a URL to pull in a Markdown file from a '
"remote source, but if you do, Dactyl won't run any "
'pre-processing on it.\n'
'Directory Paths¶\n'
'An advanced setup would probably have a directory structure '
'such as the following:\n'
'./ # Top-level dir; this is where you run '
'dactyl_*\n'
'./dactyl-config.yml # Default config file name\n'
'./content # Dir containing your .md source '
'files\n'
'---------/*/*.md # You can sort .md files into subdirs '
'if you like\n'
'---------/static/* # Static images referencd in your .md '
'files\n'
'./templates/template-*.html # Custom HTML Templates\n'
'./assets # Directory for static files '
'referenced by templates\n'
'./out # Directory where output gets '
'generated. Can be deleted\n'
'\n'
'All of these paths can be configured.\n'
'Targets¶\n'
'A target represents a group of pages, which can be built '
'together or concatenated into a single PDF. You should have at '
'least one target defined in the targets array of your Dactyl '
'config file. A target definition should consist of a short '
'name (used to specify the target in the commandline and '
'elsewhere in the config file) and a human-readable '
'display_name (used mostly by templates but also when listing '
'targets on the commandline).\n'
'A simple target definition:\n'
'targets:\n'
' - name: kc-rt-faq\n'
' display_name: Ripple Trade Migration FAQ\n'
'\n'
'In addition to name and display_name, a target definition can '
'contain arbitrary key-values to be inherited by all pages in '
'this target. Dictionary values are inherited such that keys '
"that aren't set in the page are carried over from the target, "
'recursively. The rest of the time, fields that appear in a '
'page definition take precedence over fields that appear in a '
'target definition.\n'
'Some things you may want to set at the target level include '
'filters (an array of filters to apply to pages in this '
'target), template (template to use when building HTML), and '
'pdf_template (template to use when building PDF). You can also '
'use the custom values in templates and preprocessing. Some '
"filters define additional fields that affect the filter's "
'behavior.\n'
'The following field names cannot be inherited: name, '
'display_name, and pages.\n'
'Pages¶\n'
'Each page represents one HTML file in your output. A page can '
'belong to one or more targets. When building a target, all the '
'pages belonging to that target are built in the order they '
'appear in the pages array of your Dactyl config file.\n'
'Example of a pages definition with two files:\n'
'pages:\n'
' - name: RippleAPI\n'
' category: References\n'
' html: reference-rippleapi.html\n'
' md: '
'https://raw.githubusercontent.com/ripple/ripple-lib/0.17.2/docs/index.md\n'
' filters:\n'
' - remove_doctoc\n'
' - add_version\n'
' targets:\n'
' - local\n'
' - ripple.com\n'
'\n'
' - name: rippled\n'
' category: References\n'
' html: reference-rippled.html\n'
' md: reference-rippled.md\n'
' targets:\n'
' - local\n'
' - ripple.com\n'
'\n'
'Each individual page definition can have the following '
'fields:\n'
'\n'
'\n'
'\n'
'Field\n'
'Type\n'
'Description\n'
'\n'
'\n'
'\n'
'\n'
'targets\n'
'Array\n'
'The short names of the targets that should include this page.\n'
'\n'
'\n'
'html\n'
'String\n'
'(Optional) The filename where this file should be written in '
'the output directory. If omitted, Dactyl chooses a filename '
'based on the md field (if provided), the name field (if '
'provided), or the current time (as a last resort). By default, '
'generated filenames flatten the folder structure of the md '
'files. To instead replicate the folder structure of the source '
'documents in auto-generated filenames, add '
'flatten_default_html_paths: true to the top level of your '
'Dactyl config file.\n'
'\n'
'\n'
'name\n'
'String\n'
'(Optional) Human-readable display name for this page. If '
'omitted but md is provided, Dactyl tries to guess the right '
'file name by looking at the first two lines of the md source '
'file.\n'
'\n'
'\n'
'md\n'
'String\n'
'(Optional) The markdown filename to parse to generate this '
'page, relative to the content_path in your config. If this is '
'not provided, the source file is assumed to be empty. (You '
'might do that if you use a nonstandard template for this '
'page.)\n'
'\n'
'\n'
'openapi_specification\n'
'String\n'
'(Optional) The file path or http(s) URL to an OpenAPI v3.0 '
'specification to be parsed into generated documentation. If '
'provided, this entry becomes expanded into a set of several '
'pages that describe the methods and data types defined for the '
'given API. The generated pages inherit the other fields of '
'this page object. Experimental. If the path is a relative '
'path, it is evaluated based on the directory Dactyl is called '
'from, not the content directory.\n'
'\n'
'\n'
'api_slug\n'
'String\n'
'(Optional) If this is an openapi_specification entry,\n'
'\n'
'\n'
'category\n'
'String\n'
'(Optional) The name of a category to group this page into. '
"This is used by Dactyl's built-in templates to organize the "
'table of contents.\n'
'\n'
'\n'
'template\n'
'String\n'
'(Optional) The filename of a custom Jinja HTML template to use '
'when building this page for HTML, relative to the '
'template_path in your config.\n'
'\n'
'\n'
'pdf_template\n'
'String\n'
'(Optional) The filename of a custom Jinja HTML template to use '
'when building this page for PDF, relative to the template_path '
'in your config.\n'
'\n'
'\n'
'openapi_md_template_path\n'
'String\n'
'(Optional) Path to a folder containing templates to be used '
'for OpenAPI spec parsing. If omitted, use the built-in '
'templates.\n'
'\n'
'\n'
'parent\n'
'String\n'
'(Optional) The HTML filename of the page to treat as a parent '
'of this one for purposes of hierarchy. If omitted, treat the '
'page as a "top-level" page.\n'
'\n'
'\n'
'...\n'
'(Various)\n'
'Additional arbitrary key-value pairs as desired. These values '
'can be used by templates or pre-processing.\n'
'\n'
'\n'
'\n'
'If the file specified by md begins with YAML frontmatter, '
'separated by a line of exactly ---, the frontmatter is used as '
'a basis for these fields. Certain frontmatter fields are '
'adapted from Jekyll format to Dactyl format: for example, '
'title gets copied to name if the page does not have a name.\n'
'The following fields are automatically added after a page has '
"been parsed to HTML. (They're not available when preprocessing "
'or rendering Markdown to HTML, but are available when '
'rendering HTML templates.)\n'
'\n'
'\n'
'\n'
'Field\n'
'Type\n'
'Description\n'
'\n'
'\n'
'\n'
'\n'
'plaintext\n'
'String\n'
"A plaintext-only version of the page's markdown content, with "
'all Markdown and HTML syntax removed.\n'
'\n'
'\n'
'headermap\n'
'Dictionary\n'
"A mapping of the page's headers to the unique IDs of those "
'headers in the generated HTML version.\n'
'\n'
'\n'
'blurb\n'
'String\n'
"An introductory blurb generated from the page's first "
'paragraph of text.\n'
'\n'
'\n'
'children\n'
'List\n'
'A list of pages, in order of appearance, that refer to this '
'page as their parent. Each of these "child" pages is a '
'reference to the page definition (dictionary) for that child.\n'
'\n'
'\n'
'is_ancestor_of\n'
'Function\n'
'A function that takes one argument, the string identifying a '
"potential child page by that child's html field. This function "
'returns True if this page is a direct or indirect parent of '
'the child page.\n'
'\n'
'\n',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'__dactyl_provided_filename__': True,
'blurb': 'Dactyl includes a link-checking script to automatically detect and '
'report on broken hyperlinks in your generated documentation.',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Link Checking¶': '#link-checking',
'Unusual Link Types¶': '#unusual-link-types',
'Usage¶': '#usage'},
'hover_anchors': '¶',
'html': 'link-checking.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d336e50>,
'md': 'usage/link-checking.md',
'name': 'Link Checking',
'parent': 'usage.html',
'plaintext': 'Link Checking¶\n'
'Dactyl includes a link-checking script to automatically detect '
'and report on broken hyperlinks in your generated '
'documentation.\n'
'Usage¶\n'
'First, build some documentation to an output path. Depending '
'on your configuration, you may want to build multiple targets '
'to different output directories before running the link '
'checker.\n'
'Then, run the link checker as follows:\n'
'$ dactyl_link_checker\n'
'\n'
'This checks all the files in the output directory for links '
'and confirms that any HTTP(S) links, including relative links '
'to other files, are valid. For anchor links, it checks that an '
'element with the correct ID exists in the target file. It also '
'checks that the src of all image tags exists.\n'
'If there are links that are always reported as broken but you '
"don't want to remove (for example, URLs that block Python's "
'user-agent) you can add them to the known_broken_links array '
'in the config.\n'
'In quiet mode (-q), the link checker still reports in every 30 '
"seconds just so that it doesn't get treated as stalled and "
'killed by continuous integration software (e.g. Jenkins).\n'
'To reduce the number of meaningless failure reports (because a '
'particular website happened to be down momentarily while you '
'ran the link checker), if there are any broken remote links, '
'the link checker waits 2 minutes after finishing and then '
'retries those links in case they came back up. (If they did, '
"they're not considered broken for the link checker's final "
'report.)\n'
'You can also run the link checker in offline mode (-o) to skip '
'any remote links and just check that the files and anchors '
'referenced exist in the output directory.\n'
'If you have a page that uses JavaScript or something to '
"generate anchors dynamically, the link checker can't find "
"those anchors (since it doesn't run any JS). You can add such "
'pages to the ignore_anchors_in array in your config to skip '
'checking for links that go to anchors in such pages.\n'
'Unusual Link Types¶\n'
'Some unusual types of links that you may encounter in HTML or '
'Markdown include:\n'
'\n'
'Protocol relative URL - these start with // and refer to '
'"whatever protocl is being used now". Dactyl assumes HTTPS '
'should work for these URLs.\n'
'Mailto URL - Email addresses. The link checker ignores these '
'and other links that use other URI schemes.\n'
'Javascript Bookmarklet - JavaScript code embedded in the href '
'directly with javascript:. The link checker ignores these.\n'
'Empty anchor - A link to #. This type of link is often used to '
'trigger JavaScript events. The link checker considers these '
'invalid for <img> paths but OK for <a> tags.\n',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'__dactyl_provided_filename__': True,
'blurb': 'The style checker is experimental. It is only suitable for English '
'text. It reports several details about document contents that may '
'be helpful for identifying documents whose readability you could '
'improve. These details are:',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Discouraged Words and Phrases¶': '#discouraged-words-and-phrases',
'Length Metrics¶': '#length-metrics',
'Readability Goals¶': '#readability-goals',
'Readability Scores¶': '#readability-scores',
'Spell Checking¶': '#spell-checking',
'Style Checking¶': '#style-checking'},
'hover_anchors': '¶',
'html': 'style-checking.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d336ee0>,
'md': 'usage/style-checking.md',
'name': 'Style Checking',
'parent': 'usage.html',
'plaintext': 'Style Checking¶\n'
'The style checker is experimental. It is only suitable for '
'English text. It reports several details about document '
'contents that may be helpful for identifying documents whose '
'readability you could improve. These details are:\n'
'\n'
'Discouraged words and phrases.\n'
'Page length details.\n'
'Readability scores.\n'
'Spell-checking.\n'
'\n'
'Example usage:\n'
'$ dactyl_style_checker\n'
'\n'
'The style checker re-generates contents in-memory (never '
'writing it out), unlike the link checker which requires you to '
'run dactyl_build first. It only checks contents that come from '
'Markdown, not from HTML templates.\n'
'The style checker uses the first target in the config file '
'unless you specify another target with -t. You can check just '
'one file by passing its HTML path in the --only parameter.\n'
'The exit code of the command is 0 (success) if it found no '
'discouraged words, the spell checker found no unknown words, '
'and no pages failed their configured readability goals. '
'Otherwise, the exit code of the command is 1 (failure).\n'
'Discouraged Words and Phrases¶\n'
'You can suggest specific words or phrases to discourage. The '
'style checker checks for instances of these words and phrases '
"in documents' content, and suggests alternatives based on the "
'phrase file. Dactyl does not check text in <code>, <pre>, and '
'<tt> elements since those are intended to be code samples.\n'
'To configure lists of discouraged words and phrases, add the '
'following config options:\n'
'\n'
'\n'
'\n'
'Field\n'
'Value\n'
'Description\n'
'\n'
'\n'
'\n'
'\n'
'word_substitutions_file\n'
'String\n'
'The path to a YAML file with a single top-level map. The keys '
'are the words to discourage and the values are suggestions of '
'words to replace them with.\n'
'\n'
'\n'
'phrase_substitutions_file\n'
'String\n'
'The path to a YAML file with a single top-level map. The keys '
'are phrases to discourage and the values are suggestions of '
'phrases to replace them with.\n'
'\n'
'\n'
'\n'
'You can add an exemption to a specific discouraged word/phrase '
'rule with an HTML comment. The exemption applies to the whole '
'output (HTML) file in which it appears.\n'
'Maybe the word "will" is a discouraged word, but you really '
'want to use it here without flagging it as a violation? Adding '
'a comment like this <!-- STYLE_OVERRIDE: will --> makes it '
'so.\n'
'\n'
'Spell Checking¶\n'
'Dactyl uses pyspellchecker to report possible spelling errors '
'and suggest corrections. The built-in dictionary is not very '
'thorough; you can extend it by providing a dictionary file '
'with more words. Spell checking is case-insensitive.\n'
'If you want the spell checker to skip a page, put '
'skip_spell_checker: true in the page definition.\n'
'If you want to ignore one or more words on a single page only, '
'add a comment such as the following anywhere in the page:\n'
'<!-- IGNORE_SPELLING: affectednodes, creatednode, deletednode, '
'modifiednode -->\n'
'\n'
'To extend the built-in dictionary used for all files, add the '
'following field to the config. (You cannot remove words from '
'the built-in dictionary.)\n'
'\n'
'\n'
'\n'
'Field\n'
'Value\n'
'Description\n'
'\n'
'\n'
'\n'
'\n'
'spelling_file\n'
'String\n'
'Path to a text file with words to add to the dictionary. Each '
'line of the file should contain a single word '
'(case-insensitive).\n'
'\n'
'\n'
'\n'
'Length Metrics¶\n'
'Dactyl reports the number of characters of text, number of '
'sentences, and number of words in each document. These counts '
'only include text contents (the parts generated from '
'Markdown). They do not include code samples (not even inlined '
'code words), or images/figures. The sentence counts are '
'estimates. Headings, list items, and table cells each count as '
'one sentence in these metrics. The summary includes the '
'averages across all pages, and the stats for the three longest '
'and shortest pages.\n'
'These metrics are intended to be helpful for choosing '
'documents that would be better off combined or split up. They '
'can also be useful for interpreting readability scores, which '
'tend to be less reliable for very short documents.\n'
'Readability Scores¶\n'
'The style checker reports readability scores based on several '
'formulas implemented in the textstat library. These can help '
'you identify documents with a high proportion of big words and '
'long sentences.\n'
'\n'
'Caution: Readability formulas are not very smart. Trying to '
'get a high readability score can actually decrease the clarity '
"of your writing if you aren't mindful of other factors. Things "
"readability formulas usually don't take into account include: "
'brevity; complexity of the high-level structure; logical '
'connections such as cause and effect; and precise use of '
'language. They tend to score tables and bulleted lists badly '
'even though those structure are very helpful for actual '
'readability.\n'
'\n'
'By default, Dactyl prints the readability scores for each page '
'as it analyzes them. The -q option hides this output. The '
'summary at the end lists the average scores for all pages '
'analyzed and the three pages with the worst Flesch Reading '
'Ease scores.\n'
'Readability Goals¶\n'
'You can set readability goals for individual pages or an '
'entire target by adding the readability_goals field. This '
'field should contain a map of readability metrics to target '
'scores. Goals defined for individual pages override goals set '
"for the entire target. Dactyl compares a page's readability "
'scores to any goals set and reports a list of pages that '
'failed their goals in the summary. The goal passes if the '
"page's score is equal better (easier to read) than the stated "
'goal value, and fails otherwise. For Flesch Reading Ease, '
'higher scores represent better readability; for the other '
'tests, lower scores represent better readability.\n'
'Note: Since very short pages tend to have inconsistent and '
'unreliable readability scores, Dactyl does not calculate '
'readability scores for pages with fewer than 10 "sentences". '
'(Bullet points, headings, and table cells each count as '
'separate "sentences" for this purpose.)\n'
'Example configuration:\n'
'targets:\n'
'\n'
' - name: my-target\n'
' display_name: Example Target\n'
' readability_goals:\n'
' flesch_reading_ease: 50\n'
' automated_readability_index: 12\n'
'\n'
'The available readability tests are:\n'
'\n'
'\n'
'\n'
'Field Name\n'
'Details\n'
'\n'
'\n'
'\n'
'\n'
'flesch_reading_ease\n'
'Flesch reading ease. Maximum score 121.22; no limit on how '
'negative the score can be.\n'
'\n'
'\n'
'smog_index\n'
'SMOG grade. Gives an estimated grade level.\n'
'\n'
'\n'
'coleman_liau_index\n'
'Coleman-Liau index. Gives an estimated grade level.\n'
'\n'
'\n'
'automated_readability_index\n'
'Automated readability index. Gives an estimated grade level.\n'
'\n'
'\n'
'dale_chall_readability_score\n'
'Dale-Chall readability formula. Decimal representing '
'difficulty; lower values map to lower grade levels.\n'
'\n'
'\n'
'linsear_write_formula\n'
'Linsear Write formula. Gives an estimated grade level.\n'
'\n'
'\n'
'gunning_fog\n'
'Gunning fog index. Gives an estimated grade level.\n'
'\n'
'\n'
'\n'
'Estimated grade levels are based on the United States school '
'system and are given as decimal approximations. For example, '
'11.5 represents somewhere between 11th and 12th grade (high '
'school junior to senior).',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'blurb': 'Dactyl has the ability to build JSON formatted for upload to '
'ElasticSearch and even upload it directly.',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'ElasticSearch Compatibility¶': '#elasticsearch-compatibility',
'ElasticSearch JSON Templates¶': '#elasticsearch-json-templates'},
'hover_anchors': '¶',
'html': 'elasticsearch.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d336f70>,
'md': 'usage/elasticsearch.md',
'name': 'ElasticSearch Compatibility',
'parent': 'usage.html',
'plaintext': 'ElasticSearch Compatibility¶\n'
'Dactyl has the ability to build JSON formatted for upload to '
'ElasticSearch and even upload it directly.\n'
'To build JSON files for upload to ElasticSearch, use the --es '
'mode:\n'
'dactyl_build --es\n'
'\n'
'This writes files to the usual output directory using an '
'ElasticSearch JSON template. Dactyl skips any files that do '
'not have a md source parameter in this mode. The output '
"filenames are the pages' html filenames, except ending in "
'.json instead of .html. You can specify a custom template for '
'these JSON files using the top-level default_es_template field '
'in the config file. This template must be a valid JSON file '
'and has several special properties as described in '
'ElasticSearch JSON Templates.\n'
'Dactyl can also upload these files directly to an '
'ElasticSearch instance, even when building for another mode. '
'For example, to build the HTML version of a target named '
"filterdemos but also upload that target's JSON-formatted data "
'to an ElasticSearch instance:\n'
'dactyl_build -t filterdemos --html --es_upload '
'https://my-es-instance.example.com:9200\n'
'\n'
'The parameter to --es_upload should be the base URL of your '
'ElasticSearch index. You can omit the parameter to use the '
'default base URL of http://localhost:9200.\n'
'ElasticSearch JSON Templates¶\n'
'Dactyl has a special format for JSON templates meant for '
'creating ElasticSearch data. These templates must be valid '
'JSON and are processed according to the following rules:\n'
'\n'
'Any strings in the fields\' values are "preprocessed" in a '
'similar context to the Jinja2-based Markdown preprocessor. For '
'example, the string ElasticSearch Compatibility evaluates to '
"the page's name.\n"
'Any object containing the key __dactyl_eval__ is evaluated as '
'a Python expression. The object is replaced with the results '
'of the expression, with lists becoming JSON arrays and '
'dictionaries becoming JSON objects.\n'
'The above rules apply recursively to values nested in arrays '
'and objects. All other values are preserved literally.\n'
'\n'
'The context provided to the preprocessing and to the '
'__dactyl_eval__ expressions is the same and contains the '
'following:\n'
'\n'
'\n'
'\n'
'Field\n'
'Python Type\n'
'Description\n'
'\n'
'\n'
'\n'
'\n'
'currentpage\n'
'dict\n'
'The current page definition (usually derived from the config '
'file)\n'
'\n'
'\n'
'target\n'
'dict\n'
'The current target definition (usually derived from the config '
'file)\n'
'\n'
'\n'
'categories\n'
'list\n'
'A list of unique category values used by pages in the current '
'target, in order of appearance.\n'
'\n'
'\n'
'page_filters\n'
'list\n'
'A list of the names of Dactyl filters applied to the current '
'page.\n'
'\n'
'\n'
'mode\n'
'str\n'
'Always equal to es in this context\n'
'\n'
'\n'
'current_time\n'
'str\n'
'The current time, in the time_format specified in the config. '
'(Defaults to YYYY-MM-DD)\n'
'\n'
'\n'
'bypass_errors\n'
'bool\n'
'If true, this build is running with the option to continue '
'through errors where possible.\n'
'\n'
'\n',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'__dactyl_provided_filename__': True,
'blurb': 'Dactyl can parse an OpenAPI v3.0 specification to generate API '
'documentation for the API that specification describes, including '
'API methods and object schemas.',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Ad-Hoc Usage¶': '#ad-hoc-usage',
'Config File¶': '#config-file',
'Custom Templates¶': '#custom-templates',
'OpenAPI Specifications¶': '#openapi-specifications'},
'hover_anchors': '¶',
'html': 'openapi.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a040>,
'md': 'usage/openapi.md',
'name': 'OpenAPI Specifications',
'parent': 'usage.html',
'plaintext': 'OpenAPI Specifications¶\n'
'Dactyl can parse an OpenAPI v3.0 specification to generate API '
'documentation for the API that specification describes, '
'including API methods and object schemas.\n'
'Ad-Hoc Usage¶\n'
'You can use the --openapi <specfile> parameter to build a '
'single target from\n'
'dactyl_build --openapi openapi.yaml\n'
'\n'
'You can combine this with --md or --pdf to output the '
'generated documentation in Markdown or PDF format, '
'respectively.\n'
'Config File¶\n'
'You can add a special entry to the pages array to represent an '
'API reference; Dactyl will expand that file into multiple '
'pages that each inherit any fields of this entry. For '
'example:\n'
'- openapi_specification: '
'https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml\n'
' api_slug: petstore\n'
' foo: bar\n'
' targets:\n'
' - baz\n'
'\n'
'The api_slug field is optional, and provides a prefix that '
'gets used for a bunch of file names and stuff. You can use the '
'other fields to specify which HTML templates to use or to pass '
'more info to those templates to control how they display.\n'
'The generated pages are:\n'
'\n'
'An "All Methods" table of contents, listing every path '
'operation in the paths of the OpenAPI specification.\n'
'"Tag Methods" table of contents pages for each tag used in the '
'OpenAPI specification.\n'
'Pages for all "API Methods" (path operations) in paths of the '
'OpenAPI specification.\n'
'A "Data Types" table of contents, listing every data type '
'defined in the schema section of the OpenAPI specification.\n'
'Individual pages for each data type in the OpenAPI '
"specification's schema section.\n"
'\n'
'Custom Templates¶\n'
'You can override the templates used for generated OpenAPI '
'pages to adjust how the Markdown is generated.\n'
'In the page or target definition of your config file, set the '
'openapi_md_template_path field to a path that contains the '
'following templates:\n'
'\n'
'\n'
'\n'
'Filename\n'
'Template for...\n'
'\n'
'\n'
'\n'
'\n'
'template-openapi_data_type.md\n'
"Each individual data type in the spec's schema section.\n"
'\n'
'\n'
'template-openapi_data_types_toc.md\n'
'Table of contents for the data types.\n'
'\n'
'\n'
'template-openapi_endpoint_tag_toc.md\n'
'Table of contents for each endpoint tag in the spec.\n'
'\n'
'\n'
'template-openapi_endpoint_toc.md\n'
'Table of contents for all endpoints and tags.\n'
'\n'
'\n'
'template-openapi_endpoint.md\n'
'Table of contents for each individual endpoint in the paths '
'section.\n'
'\n'
'\n'
'\n'
'These templates use Jinja syntax.',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'blurb': '',
'category': 'Features',
'children': [{'blurb': 'Dactyl automatically adds syntax highlighting to '
'code blocks.',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Code Highlighting¶': '#code-highlighting',
'Disabling¶': '#disabling',
'Languages¶': '#languages',
'Requirements¶': '#requirements'},
'hover_anchors': '¶',
'html': 'code-highlighting.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a160>,
'md': 'code-highlighting.md',
'name': 'Code Highlighting',
'parent': 'features.html',
'plaintext': 'Code Highlighting¶\n'
'Dactyl automatically adds syntax highlighting to '
'code blocks when it parses Markdown, using the '
'Pygments-derived CodeHilite extension. Parsing '
'the syntax highlighting at compile time like '
"this is faster and less work for readers' "
'computers than in-browser syntax highlighting '
'such as using highlight.js. (If you prefer '
"highlight.js's output, though, you can still run "
"it to overwrite Dactyl's syntax highlighting.)\n"
"Example of a code segment colored by Dactyl's "
'built-in highlighting:\n'
'unacceptable_chars = re.compile(r"[^A-Za-z0-9._ '
']+")\n'
'whitespace_regex = re.compile(r"\\s+")\n'
'def slugify(s):\n'
' s = re.sub(unacceptable_chars, "", s)\n'
' s = re.sub(whitespace_regex, "_", s)\n'
' if not s:\n'
' s = "_"\n'
' return s\n'
'\n'
'Requirements¶\n'
'The highlighting requires a stylesheet to define '
"the colors and styles used. Dactyl's default "
'stylesheet includes an example or you can define '
"your own. You can output one of Pygments' "
'default stylesheets from the commandline as in '
'the following example:\n'
'$ pygmentize -S default -f html -a .codehilite > '
'default.css\n'
'\n'
'Languages¶\n'
"Dactyl's code highlighting supports the same "
'programming languages that Pygments supports. By '
'default it attempts to auto-detect the language, '
'but you can add a language code to the first '
'line of a fenced code block to specify the '
'language.\n'
'Example code:\n'
'```js\n'
'function slugify(s) {\n'
' const unacceptable_chars = /[^A-Za-z0-9._ ]+/\n'
' const whitespace_regex = /\\s+/\n'
' s = s.replace(unacceptable_chars, "")\n'
' s = s.replace(whitespace_regex, "_")\n'
' s = s.toLowerCase()\n'
' if (!s) {\n'
' s = "_"\n'
' }\n'
' return s\n'
'}\n'
'```\n'
'\n'
'Output:\n'
'function slugify(s) {\n'
' const unacceptable_chars = /[^A-Za-z0-9._ ]+/\n'
' const whitespace_regex = /\\s+/\n'
' s = s.replace(unacceptable_chars, "")\n'
' s = s.replace(whitespace_regex, "_")\n'
' s = s.toLowerCase()\n'
' if (!s) {\n'
' s = "_"\n'
' }\n'
' return s\n'
'}\n'
'\n'
'Disabling¶\n'
'If for some reason you want to turn off syntax '
'highlighting, you can add no_highlighting: true '
'to your config file at the global, target, or '
'page level.',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'__dactyl_provided_filename__': True,
'blurb': 'This page demonstrates including a file using the '
"preprocessor's include syntax. The path to including "
'a file is always relative to the content_path from '
'the config.',
'category': 'Features',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Includes and Filters¶': '#includes-and-filters',
'Includes¶': '#includes',
'Other Stuff¶': '#other-stuff',
'With Conditionals¶': '#with-conditionals'},
'hover_anchors': '¶',
'html': 'includes.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a1f0>,
'md': 'includes.md',
'name': 'Includes',
'parent': 'features.html',
'plaintext': 'Includes¶\n'
'This page demonstrates including a file using '
"the preprocessor's include syntax. The path to "
'including a file is always relative to the '
'content_path from the config.\n'
'Example code:\n'
"{% include 'includes/reusable.md' %}\n"
'\n'
'Results:\n'
'This snippet of text is reusable and can be '
'included multiple times as needed, while being '
'sourced from a single file in all cases.\n'
'With Conditionals¶\n'
'Sometimes you want to use a block of text with '
'slight differences in different contexts. You '
'can use conditionals to define the different '
'text to appear or not depending on where the '
'file is being included. In most cases you can '
'check some property of the currentpage or '
"target, but in case you can't, the set tag can "
'help.\n'
'Example code:\n'
'{% set extended = True %}\n'
"{% include 'includes/reusable.md' %}\n"
'\n'
'Results:\n'
'This snippet of text is reusable and can be '
'included multiple times as needed, while being '
'sourced from a single file in all cases.\n'
'This is the extended version.\n'
'Includes and Filters¶\n'
'If you include a page that is written to use a '
'filter, you might get weird results if the '
"current page / target don't run the filter.\n"
'Other Stuff¶\n'
'Includes are part of preprocessing, so you can '
'do things like making one file that has all your '
'Markdown reference links, and including that in '
'all your pages to make the reference links '
'always available.\n'
'Reader exercise: make your own filter to '
'automatically include a page at the end of '
'another page!',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'blurb': 'Frontmatter is a set of YAML keys and values to '
'start a Markdown file, set off by two lines of ---. '
'For example, this page has the following '
'frontmatter:',
'categories': ['Tests',
'Dactyl ignores categories beyond the first'],
'category': 'Tests',
'children': [],
'demote_headers_pdf_only': True,
'desc': 'This file has Jekyll-style frontmatter',
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Frontmatter¶': '#frontmatter'},
'hover_anchors': '¶',
'html': 'frontmatter.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a280>,
'md': 'frontmatter.md',
'name': 'Frontmatter',
'parent': 'features.html',
'plaintext': 'Frontmatter¶\n'
'Frontmatter is a set of YAML keys and values to '
'start a Markdown file, set off by two lines of '
'---. For example, this page has the following '
'frontmatter:\n'
'---\n'
'desc: This file has Jekyll-style frontmatter\n'
'categories: ["Tests", "Dactyl ignores categories '
'beyond the first"]\n'
'---\n'
'\n'
'The frontmatter can be referenced by the '
'preprocessor and by templates. For example:\n'
'> Description: {{currentpage.desc}}\n'
'\n'
'Results:\n'
'\n'
'Description: This file has Jekyll-style '
'frontmatter\n'
'\n'
'Caution: If you include a page, the frontmatter '
'of the included page is not available to the '
'including page.',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'blurb': 'You can provide or override fields of the target '
'using the --vars parameter.',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Commandline Variables¶': '#commandline-variables'},
'hover_anchors': '¶',
'html': 'cli-vars.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a310>,
'md': 'cli-vars.md',
'name': 'Commandline Variables',
'parent': 'features.html',
'plaintext': 'Commandline Variables¶\n'
'You can provide or override fields of the target '
'using the --vars parameter.\n'
'For example, the following is the output of '
'{{target.foo}}: fooooooo\n'
'And the following is the output of '
'{{target.bar}}: ``\n'
'Some things to know about these variables:\n'
'\n'
'foo is defined in the config file definition for '
'the "everything" target.\n'
'bar is not defined in the config file.\n'
'\n'
'You should be able to change the output of these '
'variables using a --vars argument containing '
'either inlined JSON or the filename of a JSON '
'file with the variables to apply to the target. '
'For example:\n'
'dactyl_build --vars \'{"foo": "FOO VALUE", '
'"bar": "BAR VALUE"}\'\n'
'\n'
'or:\n'
'echo \'{"foo": "FOO VALUE", "bar": "BAR '
'VALUE"}\' > some_vars.json\n'
'dactyl_build --vars some_vars.json\n',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'__dactyl_provided_filename__': True,
'blurb': 'You can use the preprocessor to hide or show certain '
'content based on various conditions. For example, '
'you can have a page used in multiple targets, but '
'omit certain portions from the output in some '
'targets. Or, you can have text and markup that only '
'shows up in HTML mode but not PDF mode or similar '
'rules.',
'category': 'Features',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Conditionals¶': '#conditionals'},
'hover_anchors': '¶',
'html': 'conditionals.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a3a0>,
'md': 'conditionals.md',
'name': 'Conditionals',
'parent': 'features.html',
'plaintext': 'Conditionals¶\n'
'You can use the preprocessor to hide or show '
'certain content based on various conditions. For '
'example, you can have a page used in multiple '
'targets, but omit certain portions from the '
'output in some targets. Or, you can have text '
'and markup that only shows up in HTML mode but '
'not PDF mode or similar rules.\n'
'You can use any of the fields available to the '
'preprocessor for your conditionals, including '
'commandline variables and any fields defined in '
'the frontmatter.\n'
'Example of printing different text by :\n'
"{% if currentpage.condition == 'tests-2' %}\n"
'some text that only appears when the "condition" '
'field of the current page is "tests-2"\n'
'{% else %}\n'
'some text that appears when not tests-2\n'
'{% endif %}\n'
'\n'
'some text that always appears\n'
'\n'
'Result:\n'
'some text that appears when not tests-2\n'
'some text that always appears\n'
'\n'
'Example of printing different text in different\n'
"{% if mode == 'pdf' %}\n"
'This is PDF mode.\n'
"{% elif mode == 'html' %}\n"
'This is HTML mode.\n'
"{% elif mode == 'md' %}\n"
'This is MD mode (See also: `--githubify`)\n'
"{% elif mode == 'es' %}\n"
'This is ElasticSearch indexing mode (JSON).\n'
'{% else %}\n'
'We should not reach this case.\n'
'{% endif %}\n'
'\n'
'Result:\n'
'This is HTML mode.',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything', 'conditionals']},
{'__dactyl_provided_filename__': True,
'blurb': "Markdown's handling of lists and code blocks is kind "
'of ugly.',
'category': 'Features',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Lists and Code Blocks¶': '#lists-and-code-blocks',
'Things that Work¶': '#things-that-work',
"Things that don't work¶": '#things-that-dont-work'},
'hover_anchors': '¶',
'html': 'lists-and-codeblocks.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a430>,
'md': 'lists-and-codeblocks.md',
'name': 'Lists and Code Blocks Demo',
'parent': 'features.html',
'plaintext': 'Lists and Code Blocks¶\n'
"Markdown's handling of lists and code blocks is "
'kind of ugly.\n'
'Things that Work¶\n'
"Both Dactyl's markdown parser and GitHub's "
'parser handle this case correctly when you use '
'indented (not fenced) code blocks, with some '
'necessary blank lines between.\n'
'\n'
'\n'
'first list item\n'
'Descriptive text inside of 1st list item '
'(indented 4 spaces, after a blank line):\n'
'Indented, non-fenced code block, minimum 8 '
'spaces indented\n'
'\n'
'More descriptive text inside of 1st list item '
'(indented 4 spaces again):\n'
'Indented, non-fenced code block, minimum 8 '
'spaces indented\n'
'\n'
'\n'
'\n'
'second list item\n'
'\n'
'\n'
'For the record, you have to indent everything '
'another 4 spaces if you have a nested list, '
'e.g.:\n'
'\n'
'\n'
'level one list\n'
'\n'
'level two list (4 spaces indented)\n'
'\n'
'level two list item 2\n'
'Some more info on item 2\n'
'a code block inside 2\n'
'\n'
'\n'
'\n'
'\n'
'\n'
"Things that don't work¶\n"
'\n'
'This is the first item of a list.\n'
'\n'
'This is a\n'
' fenced\n'
' code\n'
' block\n'
'\n'
'\n'
"The list should resume from here, but it's "
'actually a new list instead\n'
'Is this the third list item?\n'
" It still doesn't work if the\n"
' fenced code block\n'
' is itself indented\n'
'\n'
'"Fourth" list item.\n'
'code fences turn into inline code if you indent '
'them _and_ leave a blank line\n'
"5. Also, don't number your lists with letters in "
'markdown\n'
"a. It won't get interpreted as a list\n"
'b. they get interpreted as raw text\n'
"1. so you can't put more things nested in them\n"
'\n'
'c. and if you omit a blank line it gets worse\n'
'd. the lines blur together\n'
'\n'
'\n'
'And then the list should resume.\n'
'\n',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'__dactyl_provided_filename__': True,
'blurb': 'GitHub-Flavored Markdown has some stuff that Dactyl '
"doesn't do and vice-versa, and various edge cases "
'that the two may interpret differently.',
'category': 'Features',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Code Blocks¶': '#code-blocks',
'GFM Features Not Supported¶': '#gfm-features-not-supported',
'GitHub Markdown Compatibility¶': '#github-markdown-compatibility',
'Header IDs¶': '#header-ids',
'Line Breaks¶': '#line-breaks',
'Preprocessing¶': '#preprocessing'},
'hover_anchors': '¶',
'html': 'gfm-compat.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a4c0>,
'md': 'gfm-compat.md',
'name': 'GitHub Markdown Compatibility',
'parent': 'features.html',
'plaintext': 'GitHub Markdown Compatibility¶\n'
'GitHub-Flavored Markdown has some stuff that '
"Dactyl doesn't do and vice-versa, and various "
'edge cases that the two may interpret '
'differently.\n'
'\n'
'GFM Features Not Supported\n'
'Line Breaks\n'
'Preprocessing\n'
'Header IDs\n'
'Code Blocks\n'
'\n'
'GFM Features Not Supported¶\n'
"Dactyl doesn't do any of the following:\n"
'\n'
'Automatically make URLs into hyperlinks\n'
'Emoji codes\n'
'Task lists\n'
'[x] completed\n'
'[ ] incomplete\n'
'\n'
'\n'
'Automatic references to GitHub (or GitLab) '
'issues, commits, or external resources\n'
'\n'
'Suggestion: Avoid using these.\n'
'Line Breaks¶\n'
'You can have hard-wrapped paragraphs in '
'Markdown. This\n'
'means that not every single-line break '
'introduces a\n'
"new paragraph (<p> tag). Generally, we don't "
'write\n'
'hard-wrapped text for docs, though. (It '
'introduces\n'
'unnecessary churn in diffs.)\n'
'Two paragraphs should be separated by an empty '
'line.\n'
'According to Markdown syntax, you can force a '
'mid-paragraph\n'
'line break by ending a line with two spaces\n'
'as demonstrated in this paragraph.\n'
'But watch out -- some editors (like Atom) tend '
'to strip off trailing spaces!\n'
'Preprocessing¶\n'
'Dactyl does preprocessing with Jinja, so you can '
"do conditional text and includes. GitHub doesn't "
'have stuff like that.\n'
'Suggestion: For docs that are meant to be viewed '
'on GitHub, use Dactyl\'s "Githubify mode" (TODO: '
'better docs on that) to do pre-processing only '
'and export a markdown file you can push '
'elsewhere. Be careful not to overwrite the '
'original (with the prepropessing directives) '
'with the processed export version.\n'
"Caution: The pre-processing doesn't know "
'anything about Markdown syntax, so it might '
"catch Jinja-esque syntax in things that weren't "
"meant to be interpreted as such. Use Jinja's "
'escaping syntax to fix that. E.g.:\n'
'The {% raw %} block type leaves things inside of '
'it unprocessed.\n'
'You can also use the variable delimiter to print '
"a literal, e.g. {{ '{{' }} will come out as {{\n"
'Header IDs¶\n'
'You can link to headers within a markdown '
'document because each header has a unique ID '
'based on its text.\n'
'Beware of slight differences across markdown '
"parsers. In most cases, Dactyl's header formula "
"matches GitHub's.\n"
'Caution: Header IDs are case-sensitive and '
'always lower case, for both GitHub-Flavored and '
'Dactyl markdown.\n'
'For a detailed comparison of many edge cases, '
'see Header Stress Test (Dactyl) vs. Header '
'Stress Test (GitHub Gist).\n'
'Code Blocks¶\n'
'You can do code blocks either by the "indented" '
'syntax or with code fences.\n'
'Generally, we recommend using code fences. Code '
'blocks inside lists are an exception where you '
'should use indentation to demarcate code '
'blocks.\n'
'Dactyl automatically does syntax highlighting on '
'included code blocks. If you use a language '
'definition in the code blocks, Dactyl uses that '
'to apply the correct syntax highlighting where '
'possible.',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'__dactyl_provided_filename__': True,
'blurb': 'This page demonstrates a variety of edge cases for '
'the generation of automatic IDs from header text. '
"Dactyl's generated IDs match GitHub-flavored "
'Markdown (GFM) except in cases where GFM generates '
'invalid IDs.',
'category': 'Features',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'2- Edit rippled-cfg¶': '#2-edit-rippledcfg',
'Failed to open /etc/opt/ripple/rippled-cfg¶': '#failed-to-open-etcoptripplerippledcfg',
'Header Stress Test¶': '#header-stress-test-2',
'Montréal, über, 12-89, Mère, Françoise, noël, 889¶': '#montréal-über-1289-mère-françoise-noël-889',
'Repeated Headers¶': '#repeated-headers',
'Some italic and bold text in the header-¶': '#some-italic-and-bold-text-in-the-header',
'What about angle brackets, a-k-a- < and > symbols?¶': '#what-about-angle-brackets-aka-and-symbols',
'XRP Ledgerの概要¶': '#xrp-ledgerの概要',
'account_info¶': '#account_info',
'n>1¶': '#n1',
"rippled Server Won't Start¶": '#rippled-server-wont-start',
'z͇͔̜̎̌͑ä̦̲́̃lg͖͎ọ̞̲̭̣̘̗ t̝̻̬̪͉͙͍̆̇͂ͮ̑̈̌ex͓̟̐̾t¶': '#zalgo-text',
'決済のためのデジタル資産¶': '#決済のためのデジタル資産-2',
'💩¶': '#_'},
'hover_anchors': '¶',
'html': 'header_stress_test.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a550>,
'md': 'header_stress_test.md',
'name': 'Header Stress Test',
'parent': 'features.html',
'plaintext': 'Header Stress Test¶\n'
'This page demonstrates a variety of edge cases '
'for the generation of automatic IDs from header '
"text. Dactyl's generated IDs match "
'GitHub-flavored Markdown (GFM) except in cases '
'where GFM generates invalid IDs.\n'
'2. Edit rippled.cfg¶\n'
'Lorem ipsum dolor amet seitan succulents copper '
'mug humblebrag. Synth XOXO next level '
'exercitation intelligentsia farm-to-table celiac '
'four loko esse reprehenderit artisan ennui migas '
'bitters. Plaid la croix prism man bun. Roof '
'party neutra butcher heirloom fashion axe. '
'Letterpress semiotics aliquip, palo santo lomo '
'vice man braid reprehenderit nulla raw denim put '
'a bird on it readymade. Everyday carry dolore '
'flexitarian, YOLO typewriter elit hexagon XOXO '
'cred bespoke gochujang synth.\n'
"rippled Server Won't Start¶\n"
'Cloud bread franzen drinking vinegar neutra you '
"probably haven't heard of them squid, subway "
'tile hoodie bicycle rights in live-edge. '
'Raclette cupidatat aliqua meditation truffaut. '
'Dreamcatcher yuccie roof party ramps, DIY '
'hexagon aliquip readymade aliqua PBR&B. Kitsch '
'chartreuse snackwave palo santo anim air plant '
'shabby chic. Flexitarian meggings laborum, '
'truffaut retro nostrud post-ironic trust fund '
'adipisicing mollit deserunt.\n'
'Failed to open /etc/opt/ripple/rippled.cfg¶\n'
'Does the entire path get mashed into a single '
'run-on word?\n'
'account_info¶\n'
'Single underscore—does it stay or does it go?\n'
'Some italic and bold text in the header.¶\n'
"Formatting probably doesn't contribute to the "
'header text?\n'
'What about angle brackets, a.k.a. < and > '
'symbols?¶\n'
'n>1¶\n'
'How do you link that "n>1" header, anyway? Turns '
"out on GitHub it's #n1.\n"
'XRP Ledgerの概要¶\n'
'XRP '
'Ledgerは、ピアツーピア・サーバーのネットワーク機能を備えた分散型の暗号台帳です。XRP '
'LedgerはXRPの土台となるものであり、世界中で使用されている様々な通貨の橋渡しをするために設計されたデジタル資産です。RippleはXRP '
'Ledgerの開発を主導し、「価値のインターネット」（情報が移動するようにお金が移動する世界）の実現に向けて鍵となる役割を果たすと期待されるXRPを推進しています。\n'
'決済のためのデジタル資産¶\n'
'XRPはXRP '
'Ledger固有のデジタル資産です。暗号鍵を持ち、インターネットに接続できる人は誰でも、XRPを受け取り、保持し、任意の人に送ることができます。XRPは他の通貨での取引をも容易にできる魅力的なブリッジ通貨として開発されました。XRPには次のような多くの特性があり、これにより他の多くのユースケースでも魅力的な資産となっています。\n'
'💩¶\n'
'👑📌🎇📘🔀👏🎏 👛🐩🌉🗽🔍💄 🐹🎯👤📭🏡🕖 🌅🎇💾📫🔃🌚 🌽🏪🌺🐰📛 🕐🐵🌕👎🏯 👫🏄👻👊 '
'🕦📅🎲🔄🐮🏤🏇👀🌰 👔👣🍒👠🎧🍮 💯🍪💣💔🍰 💕🏪🐹🍡🐦🎋🐁 🏈📒🐽🍢📜 💆🕜📔💧🐥 👔🔠🎱👪. '
'📣🔂🎥🌛👌🐾 🌔🐌🔋🏇🌵👄 🌅🔗💺🔣🐅👽 💞🐐🔎🌉🍌👸🍈 🍌🐸🐼📛🍁💤🍨 🍚👣💮📒🔇 '
'🎇🎥🔴🕑🕑🍊 🔃🐸👩🌼🐕 🍲🌠📆🔮 📹🐨🎻🍷🎭📼 🔼🍳💎🌏 👉🔲👉📕 🎂🎊🐸🔺🔠 🔂🔣🐍🐆👛💂. '
'🌶🔱💝🌱🐀 🔩👳🐟🐥👸 💷🌄🎶🌟🍲💃 🕙🔂🌞🔦 💔🍭💃🌁 🌆📕👈🐶📷 🎴👩👤📉🕗🔊👌 '
'🍊📟🔒🎻💃🎃 🔳🍇🔆🐢💈👧 🐲💀🍵🌱🔉 🐗📤🔼👫🔹 🍥📷🏨🐟📴 💭🍂🐎🌕💼 📊💣💆🔚👵👔 🐁🏫\n'
'Montréal, über, 12.89, Mère, Françoise, noël, '
'889¶\n'
'z͇͔̜̎̌͑ä̦̲́̃lg͖͎ọ̞̲̭̣̘̗ '
't̝̻̬̪͉͙͍̆̇͂ͮ̑̈̌ex͓̟̐̾t¶\n'
'Zalgo is to invoke the hive-mind representing '
'chaos. Invoking the feeling of chaos. Without '
'order.\n'
'Repeated Headers¶\n'
'Repeated headers should have unique IDs. But do '
'they?\n'
'Header Stress Test¶\n'
'Repeated.\n'
'Header Stress Test¶\n'
'Repeated again.\n'
'決済のためのデジタル資産¶\n'
'All-Japanese, repeated.\n'
'決済のためのデジタル資産¶\n'
'... again.',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'__dactyl_provided_filename__': True,
'blurb': '"Virtual Pages" are placeholders for pages or '
'websites that are not part of the Dactyl site, but '
'that you want to link from within the '
"Dactyl-generated navigation. Dactyl's built-in "
'templates automatically create links to virtual '
'pages in the appropriate places within the '
'navigation.',
'category': 'Features',
'children': [{'blurb': 'This is a placeholder that shows up in '
'navigation but does not have an actual '
'output file. Use this if you want to '
'link to external resources at a '
'specific place in your navigation.',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'hover_anchors': '¶',
'html': 'https://dactyl.link/#',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a670>,
'name': 'Dactyl Homepage',
'parent': 'virtual-pages.html',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'blurb': 'This is an example of a virtual page '
'defined by MD frontmatter.',
'category': 'Features',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'hover_anchors': '¶',
'html': 'https://dactyl.link/',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a700>,
'md': 'virtual-placeholder.md',
'name': 'Virtual Placeholder',
'parent': 'virtual-pages.html',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']}],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Virtual Pages¶': '#virtual-pages'},
'hover_anchors': '¶',
'html': 'virtual-pages.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a5e0>,
'md': 'virtual-pages.md',
'name': 'Virtual Pages',
'parent': 'features.html',
'plaintext': 'Virtual Pages¶\n'
'"Virtual Pages" are placeholders for pages or '
'websites that are not part of the Dactyl site, '
'but that you want to link from within the '
"Dactyl-generated navigation. Dactyl's built-in "
'templates automatically create links to virtual '
'pages in the appropriate places within the '
'navigation.\n'
'Dactyl does not build an associated output HTML '
'file for these pages, so they are linked from '
'PDF builds but their contents are not part of '
'the generated PDF. The link checker treats '
'virtual pages the same as other external links, '
'so it checks links to them but not in the '
'virtual pages.\n'
'The "Dactyl Homepage" link listed under this '
'page is an example of a Virtual Page. To create '
'a virtual link, add a stanza such as the '
'following to the page array in your config '
'file:\n'
'- name: Dactyl Homepage\n'
' parent: virtual-pages.html\n'
' html: https://dactyl.link/\n'
' targets:\n'
' - everything\n'
'\n'
'Specifically, a virtual page is any page with // '
'in its html attribute.\n'
'You can also define a virtual page using a .md '
'file with frontmatter. For example, you could '
'have a file with the following contents:\n'
'---\n'
'html: https://dactyl.link/\n'
'blurb: This is an example of a virtual page '
'defined by MD frontmatter.\n'
'category: Features\n'
'parent: virtual-pages.html\n'
'---\n'
'# Virtual Placeholder\n'
'\n'
'The actual Markdown contents of a "virtual page" '
'are mostly ignored. However, they can be used to '
'provide metadata such as the title and blurb '
'used in navigation on other pages.\n',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']}],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {},
'hover_anchors': '¶',
'html': 'features.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a0d0>,
'name': 'Features',
'parent': 'index.html',
'plaintext': '',
'section_header': True,
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything'],
'template': 'landing.html'},
{'blurb': 'Dactyl automatically adds syntax highlighting to code blocks.',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Code Highlighting¶': '#code-highlighting',
'Disabling¶': '#disabling',
'Languages¶': '#languages',
'Requirements¶': '#requirements'},
'hover_anchors': '¶',
'html': 'code-highlighting.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a160>,
'md': 'code-highlighting.md',
'name': 'Code Highlighting',
'parent': 'features.html',
'plaintext': 'Code Highlighting¶\n'
'Dactyl automatically adds syntax highlighting to code blocks '
'when it parses Markdown, using the Pygments-derived CodeHilite '
'extension. Parsing the syntax highlighting at compile time '
"like this is faster and less work for readers' computers than "
'in-browser syntax highlighting such as using highlight.js. (If '
"you prefer highlight.js's output, though, you can still run it "
"to overwrite Dactyl's syntax highlighting.)\n"
"Example of a code segment colored by Dactyl's built-in "
'highlighting:\n'
'unacceptable_chars = re.compile(r"[^A-Za-z0-9._ ]+")\n'
'whitespace_regex = re.compile(r"\\s+")\n'
'def slugify(s):\n'
' s = re.sub(unacceptable_chars, "", s)\n'
' s = re.sub(whitespace_regex, "_", s)\n'
' if not s:\n'
' s = "_"\n'
' return s\n'
'\n'
'Requirements¶\n'
'The highlighting requires a stylesheet to define the colors '
"and styles used. Dactyl's default stylesheet includes an "
'example or you can define your own. You can output one of '
"Pygments' default stylesheets from the commandline as in the "
'following example:\n'
'$ pygmentize -S default -f html -a .codehilite > default.css\n'
'\n'
'Languages¶\n'
"Dactyl's code highlighting supports the same programming "
'languages that Pygments supports. By default it attempts to '
'auto-detect the language, but you can add a language code to '
'the first line of a fenced code block to specify the '
'language.\n'
'Example code:\n'
'```js\n'
'function slugify(s) {\n'
' const unacceptable_chars = /[^A-Za-z0-9._ ]+/\n'
' const whitespace_regex = /\\s+/\n'
' s = s.replace(unacceptable_chars, "")\n'
' s = s.replace(whitespace_regex, "_")\n'
' s = s.toLowerCase()\n'
' if (!s) {\n'
' s = "_"\n'
' }\n'
' return s\n'
'}\n'
'```\n'
'\n'
'Output:\n'
'function slugify(s) {\n'
' const unacceptable_chars = /[^A-Za-z0-9._ ]+/\n'
' const whitespace_regex = /\\s+/\n'
' s = s.replace(unacceptable_chars, "")\n'
' s = s.replace(whitespace_regex, "_")\n'
' s = s.toLowerCase()\n'
' if (!s) {\n'
' s = "_"\n'
' }\n'
' return s\n'
'}\n'
'\n'
'Disabling¶\n'
'If for some reason you want to turn off syntax highlighting, '
'you can add no_highlighting: true to your config file at the '
'global, target, or page level.',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'__dactyl_provided_filename__': True,
'blurb': "This page demonstrates including a file using the preprocessor's "
'include syntax. The path to including a file is always relative to '
'the content_path from the config.',
'category': 'Features',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Includes and Filters¶': '#includes-and-filters',
'Includes¶': '#includes',
'Other Stuff¶': '#other-stuff',
'With Conditionals¶': '#with-conditionals'},
'hover_anchors': '¶',
'html': 'includes.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a1f0>,
'md': 'includes.md',
'name': 'Includes',
'parent': 'features.html',
'plaintext': 'Includes¶\n'
'This page demonstrates including a file using the '
"preprocessor's include syntax. The path to including a file is "
'always relative to the content_path from the config.\n'
'Example code:\n'
"{% include 'includes/reusable.md' %}\n"
'\n'
'Results:\n'
'This snippet of text is reusable and can be included multiple '
'times as needed, while being sourced from a single file in all '
'cases.\n'
'With Conditionals¶\n'
'Sometimes you want to use a block of text with slight '
'differences in different contexts. You can use conditionals to '
'define the different text to appear or not depending on where '
'the file is being included. In most cases you can check some '
"property of the currentpage or target, but in case you can't, "
'the set tag can help.\n'
'Example code:\n'
'{% set extended = True %}\n'
"{% include 'includes/reusable.md' %}\n"
'\n'
'Results:\n'
'This snippet of text is reusable and can be included multiple '
'times as needed, while being sourced from a single file in all '
'cases.\n'
'This is the extended version.\n'
'Includes and Filters¶\n'
'If you include a page that is written to use a filter, you '
"might get weird results if the current page / target don't run "
'the filter.\n'
'Other Stuff¶\n'
'Includes are part of preprocessing, so you can do things like '
'making one file that has all your Markdown reference links, '
'and including that in all your pages to make the reference '
'links always available.\n'
'Reader exercise: make your own filter to automatically include '
'a page at the end of another page!',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'blurb': 'Frontmatter is a set of YAML keys and values to start a Markdown '
'file, set off by two lines of ---. For example, this page has the '
'following frontmatter:',
'categories': ['Tests', 'Dactyl ignores categories beyond the first'],
'category': 'Tests',
'children': [],
'demote_headers_pdf_only': True,
'desc': 'This file has Jekyll-style frontmatter',
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Frontmatter¶': '#frontmatter'},
'hover_anchors': '¶',
'html': 'frontmatter.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a280>,
'md': 'frontmatter.md',
'name': 'Frontmatter',
'parent': 'features.html',
'plaintext': 'Frontmatter¶\n'
'Frontmatter is a set of YAML keys and values to start a '
'Markdown file, set off by two lines of ---. For example, this '
'page has the following frontmatter:\n'
'---\n'
'desc: This file has Jekyll-style frontmatter\n'
'categories: ["Tests", "Dactyl ignores categories beyond the '
'first"]\n'
'---\n'
'\n'
'The frontmatter can be referenced by the preprocessor and by '
'templates. For example:\n'
'> Description: {{currentpage.desc}}\n'
'\n'
'Results:\n'
'\n'
'Description: This file has Jekyll-style frontmatter\n'
'\n'
'Caution: If you include a page, the frontmatter of the '
'included page is not available to the including page.',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'blurb': 'You can provide or override fields of the target using the --vars '
'parameter.',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Commandline Variables¶': '#commandline-variables'},
'hover_anchors': '¶',
'html': 'cli-vars.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a310>,
'md': 'cli-vars.md',
'name': 'Commandline Variables',
'parent': 'features.html',
'plaintext': 'Commandline Variables¶\n'
'You can provide or override fields of the target using the '
'--vars parameter.\n'
'For example, the following is the output of {{target.foo}}: '
'fooooooo\n'
'And the following is the output of {{target.bar}}: ``\n'
'Some things to know about these variables:\n'
'\n'
'foo is defined in the config file definition for the '
'"everything" target.\n'
'bar is not defined in the config file.\n'
'\n'
'You should be able to change the output of these variables '
'using a --vars argument containing either inlined JSON or the '
'filename of a JSON file with the variables to apply to the '
'target. For example:\n'
'dactyl_build --vars \'{"foo": "FOO VALUE", "bar": "BAR '
'VALUE"}\'\n'
'\n'
'or:\n'
'echo \'{"foo": "FOO VALUE", "bar": "BAR VALUE"}\' > '
'some_vars.json\n'
'dactyl_build --vars some_vars.json\n',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'__dactyl_provided_filename__': True,
'blurb': 'You can use the preprocessor to hide or show certain content based '
'on various conditions. For example, you can have a page used in '
'multiple targets, but omit certain portions from the output in '
'some targets. Or, you can have text and markup that only shows up '
'in HTML mode but not PDF mode or similar rules.',
'category': 'Features',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Conditionals¶': '#conditionals'},
'hover_anchors': '¶',
'html': 'conditionals.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a3a0>,
'md': 'conditionals.md',
'name': 'Conditionals',
'parent': 'features.html',
'plaintext': 'Conditionals¶\n'
'You can use the preprocessor to hide or show certain content '
'based on various conditions. For example, you can have a page '
'used in multiple targets, but omit certain portions from the '
'output in some targets. Or, you can have text and markup that '
'only shows up in HTML mode but not PDF mode or similar rules.\n'
'You can use any of the fields available to the preprocessor '
'for your conditionals, including commandline variables and any '
'fields defined in the frontmatter.\n'
'Example of printing different text by :\n'
"{% if currentpage.condition == 'tests-2' %}\n"
'some text that only appears when the "condition" field of the '
'current page is "tests-2"\n'
'{% else %}\n'
'some text that appears when not tests-2\n'
'{% endif %}\n'
'\n'
'some text that always appears\n'
'\n'
'Result:\n'
'some text that appears when not tests-2\n'
'some text that always appears\n'
'\n'
'Example of printing different text in different\n'
"{% if mode == 'pdf' %}\n"
'This is PDF mode.\n'
"{% elif mode == 'html' %}\n"
'This is HTML mode.\n'
"{% elif mode == 'md' %}\n"
'This is MD mode (See also: `--githubify`)\n'
"{% elif mode == 'es' %}\n"
'This is ElasticSearch indexing mode (JSON).\n'
'{% else %}\n'
'We should not reach this case.\n'
'{% endif %}\n'
'\n'
'Result:\n'
'This is HTML mode.',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything', 'conditionals']},
{'__dactyl_provided_filename__': True,
'blurb': "Markdown's handling of lists and code blocks is kind of ugly.",
'category': 'Features',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Lists and Code Blocks¶': '#lists-and-code-blocks',
'Things that Work¶': '#things-that-work',
"Things that don't work¶": '#things-that-dont-work'},
'hover_anchors': '¶',
'html': 'lists-and-codeblocks.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a430>,
'md': 'lists-and-codeblocks.md',
'name': 'Lists and Code Blocks Demo',
'parent': 'features.html',
'plaintext': 'Lists and Code Blocks¶\n'
"Markdown's handling of lists and code blocks is kind of ugly.\n"
'Things that Work¶\n'
"Both Dactyl's markdown parser and GitHub's parser handle this "
'case correctly when you use indented (not fenced) code blocks, '
'with some necessary blank lines between.\n'
'\n'
'\n'
'first list item\n'
'Descriptive text inside of 1st list item (indented 4 spaces, '
'after a blank line):\n'
'Indented, non-fenced code block, minimum 8 spaces indented\n'
'\n'
'More descriptive text inside of 1st list item (indented 4 '
'spaces again):\n'
'Indented, non-fenced code block, minimum 8 spaces indented\n'
'\n'
'\n'
'\n'
'second list item\n'
'\n'
'\n'
'For the record, you have to indent everything another 4 spaces '
'if you have a nested list, e.g.:\n'
'\n'
'\n'
'level one list\n'
'\n'
'level two list (4 spaces indented)\n'
'\n'
'level two list item 2\n'
'Some more info on item 2\n'
'a code block inside 2\n'
'\n'
'\n'
'\n'
'\n'
'\n'
"Things that don't work¶\n"
'\n'
'This is the first item of a list.\n'
'\n'
'This is a\n'
' fenced\n'
' code\n'
' block\n'
'\n'
'\n'
"The list should resume from here, but it's actually a new list "
'instead\n'
'Is this the third list item?\n'
" It still doesn't work if the\n"
' fenced code block\n'
' is itself indented\n'
'\n'
'"Fourth" list item.\n'
'code fences turn into inline code if you indent them _and_ '
'leave a blank line\n'
"5. Also, don't number your lists with letters in markdown\n"
"a. It won't get interpreted as a list\n"
'b. they get interpreted as raw text\n'
"1. so you can't put more things nested in them\n"
'\n'
'c. and if you omit a blank line it gets worse\n'
'd. the lines blur together\n'
'\n'
'\n'
'And then the list should resume.\n'
'\n',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'__dactyl_provided_filename__': True,
'blurb': "GitHub-Flavored Markdown has some stuff that Dactyl doesn't do and "
'vice-versa, and various edge cases that the two may interpret '
'differently.',
'category': 'Features',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Code Blocks¶': '#code-blocks',
'GFM Features Not Supported¶': '#gfm-features-not-supported',
'GitHub Markdown Compatibility¶': '#github-markdown-compatibility',
'Header IDs¶': '#header-ids',
'Line Breaks¶': '#line-breaks',
'Preprocessing¶': '#preprocessing'},
'hover_anchors': '¶',
'html': 'gfm-compat.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a4c0>,
'md': 'gfm-compat.md',
'name': 'GitHub Markdown Compatibility',
'parent': 'features.html',
'plaintext': 'GitHub Markdown Compatibility¶\n'
"GitHub-Flavored Markdown has some stuff that Dactyl doesn't do "
'and vice-versa, and various edge cases that the two may '
'interpret differently.\n'
'\n'
'GFM Features Not Supported\n'
'Line Breaks\n'
'Preprocessing\n'
'Header IDs\n'
'Code Blocks\n'
'\n'
'GFM Features Not Supported¶\n'
"Dactyl doesn't do any of the following:\n"
'\n'
'Automatically make URLs into hyperlinks\n'
'Emoji codes\n'
'Task lists\n'
'[x] completed\n'
'[ ] incomplete\n'
'\n'
'\n'
'Automatic references to GitHub (or GitLab) issues, commits, or '
'external resources\n'
'\n'
'Suggestion: Avoid using these.\n'
'Line Breaks¶\n'
'You can have hard-wrapped paragraphs in Markdown. This\n'
'means that not every single-line break introduces a\n'
"new paragraph (<p> tag). Generally, we don't write\n"
'hard-wrapped text for docs, though. (It introduces\n'
'unnecessary churn in diffs.)\n'
'Two paragraphs should be separated by an empty line.\n'
'According to Markdown syntax, you can force a mid-paragraph\n'
'line break by ending a line with two spaces\n'
'as demonstrated in this paragraph.\n'
'But watch out -- some editors (like Atom) tend to strip off '
'trailing spaces!\n'
'Preprocessing¶\n'
'Dactyl does preprocessing with Jinja, so you can do '
"conditional text and includes. GitHub doesn't have stuff like "
'that.\n'
'Suggestion: For docs that are meant to be viewed on GitHub, '
'use Dactyl\'s "Githubify mode" (TODO: better docs on that) to '
'do pre-processing only and export a markdown file you can push '
'elsewhere. Be careful not to overwrite the original (with the '
'prepropessing directives) with the processed export version.\n'
"Caution: The pre-processing doesn't know anything about "
'Markdown syntax, so it might catch Jinja-esque syntax in '
"things that weren't meant to be interpreted as such. Use "
"Jinja's escaping syntax to fix that. E.g.:\n"
'The {% raw %} block type leaves things inside of it '
'unprocessed.\n'
'You can also use the variable delimiter to print a literal, '
"e.g. {{ '{{' }} will come out as {{\n"
'Header IDs¶\n'
'You can link to headers within a markdown document because '
'each header has a unique ID based on its text.\n'
'Beware of slight differences across markdown parsers. In most '
"cases, Dactyl's header formula matches GitHub's.\n"
'Caution: Header IDs are case-sensitive and always lower case, '
'for both GitHub-Flavored and Dactyl markdown.\n'
'For a detailed comparison of many edge cases, see Header '
'Stress Test (Dactyl) vs. Header Stress Test (GitHub Gist).\n'
'Code Blocks¶\n'
'You can do code blocks either by the "indented" syntax or with '
'code fences.\n'
'Generally, we recommend using code fences. Code blocks inside '
'lists are an exception where you should use indentation to '
'demarcate code blocks.\n'
'Dactyl automatically does syntax highlighting on included code '
'blocks. If you use a language definition in the code blocks, '
'Dactyl uses that to apply the correct syntax highlighting '
'where possible.',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'__dactyl_provided_filename__': True,
'blurb': 'This page demonstrates a variety of edge cases for the generation '
"of automatic IDs from header text. Dactyl's generated IDs match "
'GitHub-flavored Markdown (GFM) except in cases where GFM generates '
'invalid IDs.',
'category': 'Features',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'2- Edit rippled-cfg¶': '#2-edit-rippledcfg',
'Failed to open /etc/opt/ripple/rippled-cfg¶': '#failed-to-open-etcoptripplerippledcfg',
'Header Stress Test¶': '#header-stress-test-2',
'Montréal, über, 12-89, Mère, Françoise, noël, 889¶': '#montréal-über-1289-mère-françoise-noël-889',
'Repeated Headers¶': '#repeated-headers',
'Some italic and bold text in the header-¶': '#some-italic-and-bold-text-in-the-header',
'What about angle brackets, a-k-a- < and > symbols?¶': '#what-about-angle-brackets-aka-and-symbols',
'XRP Ledgerの概要¶': '#xrp-ledgerの概要',
'account_info¶': '#account_info',
'n>1¶': '#n1',
"rippled Server Won't Start¶": '#rippled-server-wont-start',
'z͇͔̜̎̌͑ä̦̲́̃lg͖͎ọ̞̲̭̣̘̗ t̝̻̬̪͉͙͍̆̇͂ͮ̑̈̌ex͓̟̐̾t¶': '#zalgo-text',
'決済のためのデジタル資産¶': '#決済のためのデジタル資産-2',
'💩¶': '#_'},
'hover_anchors': '¶',
'html': 'header_stress_test.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a550>,
'md': 'header_stress_test.md',
'name': 'Header Stress Test',
'parent': 'features.html',
'plaintext': 'Header Stress Test¶\n'
'This page demonstrates a variety of edge cases for the '
"generation of automatic IDs from header text. Dactyl's "
'generated IDs match GitHub-flavored Markdown (GFM) except in '
'cases where GFM generates invalid IDs.\n'
'2. Edit rippled.cfg¶\n'
'Lorem ipsum dolor amet seitan succulents copper mug '
'humblebrag. Synth XOXO next level exercitation intelligentsia '
'farm-to-table celiac four loko esse reprehenderit artisan '
'ennui migas bitters. Plaid la croix prism man bun. Roof party '
'neutra butcher heirloom fashion axe. Letterpress semiotics '
'aliquip, palo santo lomo vice man braid reprehenderit nulla '
'raw denim put a bird on it readymade. Everyday carry dolore '
'flexitarian, YOLO typewriter elit hexagon XOXO cred bespoke '
'gochujang synth.\n'
"rippled Server Won't Start¶\n"
'Cloud bread franzen drinking vinegar neutra you probably '
"haven't heard of them squid, subway tile hoodie bicycle rights "
'in live-edge. Raclette cupidatat aliqua meditation truffaut. '
'Dreamcatcher yuccie roof party ramps, DIY hexagon aliquip '
'readymade aliqua PBR&B. Kitsch chartreuse snackwave palo santo '
'anim air plant shabby chic. Flexitarian meggings laborum, '
'truffaut retro nostrud post-ironic trust fund adipisicing '
'mollit deserunt.\n'
'Failed to open /etc/opt/ripple/rippled.cfg¶\n'
'Does the entire path get mashed into a single run-on word?\n'
'account_info¶\n'
'Single underscore—does it stay or does it go?\n'
'Some italic and bold text in the header.¶\n'
"Formatting probably doesn't contribute to the header text?\n"
'What about angle brackets, a.k.a. < and > symbols?¶\n'
'n>1¶\n'
'How do you link that "n>1" header, anyway? Turns out on GitHub '
"it's #n1.\n"
'XRP Ledgerの概要¶\n'
'XRP Ledgerは、ピアツーピア・サーバーのネットワーク機能を備えた分散型の暗号台帳です。XRP '
'LedgerはXRPの土台となるものであり、世界中で使用されている様々な通貨の橋渡しをするために設計されたデジタル資産です。RippleはXRP '
'Ledgerの開発を主導し、「価値のインターネット」（情報が移動するようにお金が移動する世界）の実現に向けて鍵となる役割を果たすと期待されるXRPを推進しています。\n'
'決済のためのデジタル資産¶\n'
'XRPはXRP '
'Ledger固有のデジタル資産です。暗号鍵を持ち、インターネットに接続できる人は誰でも、XRPを受け取り、保持し、任意の人に送ることができます。XRPは他の通貨での取引をも容易にできる魅力的なブリッジ通貨として開発されました。XRPには次のような多くの特性があり、これにより他の多くのユースケースでも魅力的な資産となっています。\n'
'💩¶\n'
'👑📌🎇📘🔀👏🎏 👛🐩🌉🗽🔍💄 🐹🎯👤📭🏡🕖 🌅🎇💾📫🔃🌚 🌽🏪🌺🐰📛 🕐🐵🌕👎🏯 👫🏄👻👊 🕦📅🎲🔄🐮🏤🏇👀🌰 👔👣🍒👠🎧🍮 '
'💯🍪💣💔🍰 💕🏪🐹🍡🐦🎋🐁 🏈📒🐽🍢📜 💆🕜📔💧🐥 👔🔠🎱👪. 📣🔂🎥🌛👌🐾 🌔🐌🔋🏇🌵👄 🌅🔗💺🔣🐅👽 💞🐐🔎🌉🍌👸🍈 '
'🍌🐸🐼📛🍁💤🍨 🍚👣💮📒🔇 🎇🎥🔴🕑🕑🍊 🔃🐸👩🌼🐕 🍲🌠📆🔮 📹🐨🎻🍷🎭📼 🔼🍳💎🌏 👉🔲👉📕 🎂🎊🐸🔺🔠 🔂🔣🐍🐆👛💂. '
'🌶🔱💝🌱🐀 🔩👳🐟🐥👸 💷🌄🎶🌟🍲💃 🕙🔂🌞🔦 💔🍭💃🌁 🌆📕👈🐶📷 🎴👩👤📉🕗🔊👌 🍊📟🔒🎻💃🎃 🔳🍇🔆🐢💈👧 🐲💀🍵🌱🔉 '
'🐗📤🔼👫🔹 🍥📷🏨🐟📴 💭🍂🐎🌕💼 📊💣💆🔚👵👔 🐁🏫\n'
'Montréal, über, 12.89, Mère, Françoise, noël, 889¶\n'
'z͇͔̜̎̌͑ä̦̲́̃lg͖͎ọ̞̲̭̣̘̗ t̝̻̬̪͉͙͍̆̇͂ͮ̑̈̌ex͓̟̐̾t¶\n'
'Zalgo is to invoke the hive-mind representing chaos. Invoking '
'the feeling of chaos. Without order.\n'
'Repeated Headers¶\n'
'Repeated headers should have unique IDs. But do they?\n'
'Header Stress Test¶\n'
'Repeated.\n'
'Header Stress Test¶\n'
'Repeated again.\n'
'決済のためのデジタル資産¶\n'
'All-Japanese, repeated.\n'
'決済のためのデジタル資産¶\n'
'... again.',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'__dactyl_provided_filename__': True,
'blurb': '"Virtual Pages" are placeholders for pages or websites that are '
'not part of the Dactyl site, but that you want to link from within '
"the Dactyl-generated navigation. Dactyl's built-in templates "
'automatically create links to virtual pages in the appropriate '
'places within the navigation.',
'category': 'Features',
'children': [{'blurb': 'This is a placeholder that shows up in navigation '
'but does not have an actual output file. Use this if '
'you want to link to external resources at a specific '
'place in your navigation.',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'hover_anchors': '¶',
'html': 'https://dactyl.link/#',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a670>,
'name': 'Dactyl Homepage',
'parent': 'virtual-pages.html',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'blurb': 'This is an example of a virtual page defined by MD '
'frontmatter.',
'category': 'Features',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'hover_anchors': '¶',
'html': 'https://dactyl.link/',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a700>,
'md': 'virtual-placeholder.md',
'name': 'Virtual Placeholder',
'parent': 'virtual-pages.html',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']}],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Virtual Pages¶': '#virtual-pages'},
'hover_anchors': '¶',
'html': 'virtual-pages.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a5e0>,
'md': 'virtual-pages.md',
'name': 'Virtual Pages',
'parent': 'features.html',
'plaintext': 'Virtual Pages¶\n'
'"Virtual Pages" are placeholders for pages or websites that '
'are not part of the Dactyl site, but that you want to link '
"from within the Dactyl-generated navigation. Dactyl's built-in "
'templates automatically create links to virtual pages in the '
'appropriate places within the navigation.\n'
'Dactyl does not build an associated output HTML file for these '
'pages, so they are linked from PDF builds but their contents '
'are not part of the generated PDF. The link checker treats '
'virtual pages the same as other external links, so it checks '
'links to them but not in the virtual pages.\n'
'The "Dactyl Homepage" link listed under this page is an '
'example of a Virtual Page. To create a virtual link, add a '
'stanza such as the following to the page array in your config '
'file:\n'
'- name: Dactyl Homepage\n'
' parent: virtual-pages.html\n'
' html: https://dactyl.link/\n'
' targets:\n'
' - everything\n'
'\n'
'Specifically, a virtual page is any page with // in its html '
'attribute.\n'
'You can also define a virtual page using a .md file with '
'frontmatter. For example, you could have a file with the '
'following contents:\n'
'---\n'
'html: https://dactyl.link/\n'
'blurb: This is an example of a virtual page defined by MD '
'frontmatter.\n'
'category: Features\n'
'parent: virtual-pages.html\n'
'---\n'
'# Virtual Placeholder\n'
'\n'
'The actual Markdown contents of a "virtual page" are mostly '
'ignored. However, they can be used to provide metadata such as '
'the title and blurb used in navigation on other pages.\n',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'blurb': 'This is a placeholder that shows up in navigation but does not '
'have an actual output file. Use this if you want to link to '
'external resources at a specific place in your navigation.',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'hover_anchors': '¶',
'html': 'https://dactyl.link/#',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a670>,
'name': 'Dactyl Homepage',
'parent': 'virtual-pages.html',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'blurb': 'This is an example of a virtual page defined by MD frontmatter.',
'category': 'Features',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'hover_anchors': '¶',
'html': 'https://dactyl.link/',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a700>,
'md': 'virtual-placeholder.md',
'name': 'Virtual Placeholder',
'parent': 'virtual-pages.html',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'__dactyl_provided_filename__': True,
'blurb': 'Dactyl supports additional custom post-processing through the use '
'of filters which are essentially custom plugins. Filters can '
"operate on the markdown (after it's been pre-processed), on the "
"raw HTML (after it's been parsed), or on a BeautifulSoup object "
'representing the output HTML. Filters can also export functions '
'and values that are available to the preprocessor.',
'category': 'Filters',
'children': [{'__dactyl_provided_filename__': True,
'blurb': 'Callouts are a specially-colored blocks that call '
'attention to particular bits of information. They '
'might be special warnings, asides, or other details. '
'To use callouts, the page (or target) has to have '
'the callouts filter enabled, then provide syntax '
'such as the following:',
'category': 'Filters',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers', 'callouts'],
'foo': 'fooooooo',
'headermap': {'Callouts Demonstration¶': '#callouts-demonstration',
'Cases to Avoid¶': '#cases-to-avoid',
'Custom Callout Types¶': '#custom-callout-types',
'Multiline Callouts¶': '#multiline-callouts'},
'hover_anchors': '¶',
'html': 'callouts.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a820>,
'md': 'filters/callouts.md',
'name': 'Callouts Demonstration',
'parent': 'filters.html',
'plaintext': 'Callouts Demonstration¶\n'
'Callouts are a specially-colored blocks that '
'call attention to particular bits of '
'information. They might be special warnings, '
'asides, or other details. To use callouts, the '
'page (or target) has to have the callouts filter '
'enabled, then provide syntax such as the '
'following:\n'
'**Tip:** This is a "Tip" callout, styled with '
'green and a checkmark by default.\n'
'\n'
'Tip: This is a "Tip" callout, styled with green '
'and a checkmark by default.\n'
'Note: Callouts have four types by default: '
'"Note", "Tip", "Caution", and "Warning".\n'
'Caution: Be sure not to overuse callouts.\n'
'Warning: Callouts are very specific. **Note:** '
"triggers a callout; **Notes:** doesn't. The "
'colon is optional, though.\n'
'Multiline Callouts¶\n'
'\n'
'Tip: Multiline callouts with blockquotes are now '
'possible.\n'
'\n'
'Do this to include bulleted lists.\n'
'Or other types of lists.\n'
'\n'
'\n'
'\n'
'Code example:\n'
'> **Tip:** Multiline callouts with blockquotes '
'are now possible.\n'
'>\n'
'> - Do this to include bulleted lists.\n'
'> - Or other types of lists.\n'
'>\n'
'\n'
'If you have a callout word like tip bolded '
'mid-paragraph, it should not become a callout.\n'
'\n'
'Please note that this also applies to '
'blockquotes.\n'
'\n'
'There is a difficult edge case for blockquotes '
'where a paragraph other than the first one '
'starts with a callout keyword:\n'
'\n'
'This is the start of a blockquote that is not, '
'itself, a callout.\n'
'Note: This callout occurs in the middle of a '
'blockquote.\n'
'But the blockquote containing it is not, itself, '
'a callout.\n'
'\n'
'Also, note that you can cannot use code fences '
'in blockquotes.\n'
'\n'
"Caution: Code fences in blockquotes don't work "
'right.\n'
'js\n'
'if (true) {\n'
" console.log('this line of code should be "
"indented');\n"
'}\n'
'The code fence gets treated as inlined code text '
'instead. This is a limitation of '
'Python-Markdown.\n'
'\n'
'You can, however, use indented code blocks in '
'blockquotes:\n'
'\n'
'Tip: To get a proper code block in a blockquote, '
'provide a single\n'
'line of just the blockquote intro >, and indent '
'the code block 5 spaces.\n'
'print("Hello world!")\n'
'if True:\n'
' print("Note that extra spaces beyond the '
'initial 5 carry over.")\n'
'\n'
'To continue the block quote afterwords, leave a '
'near-blank line similarly.\n'
'Do not use code fences in a blockquote: they '
"don't work as expected.\n"
'\n'
'Cases to Avoid¶\n'
'\n'
'In a list, the callout applies to the whole list '
'item.\n'
'Tip: You can have callouts nested in a list.\n'
"Warning: You probably wouldn't like what happens "
'if you nest callouts in list items that are '
'already callouts.\n'
'\n'
'\n'
'\n'
'\n'
"One more point. Note: The callout doesn't "
"trigger if it's not at the start of the "
'element.\n'
'\n'
'\n'
'\n'
'\n'
'Table\n'
'Stuff\n'
'\n'
'\n'
'\n'
'\n'
'Warning: Callout syntax in table cells is '
'weird.\n'
"So it's probably best not to do that.\n"
'\n'
'\n'
'Probably.\n'
'Caution: It could maybe work better with better '
'CSS.\n'
'\n'
'\n'
'\n'
'Custom Callout Types¶\n'
'You can define additional callout types if you '
'want. This requires two pieces:\n'
'\n'
'A list of what words should trigger a callout.\n'
'CSS styles for the relevant callout types.\n'
'\n'
'To define custom callout classes, write the '
'trigger words (case-insensitive) in your '
"project's Dactyl config file. This overwrites "
'the default list, so include the default four if '
'you still want to use them. For example:\n'
'callout_types:\n'
' - "tip"\n'
' - "ヒント" # equiv. of "Tip" in Japanese (lit. '
'"Hint")\n'
' - "note"\n'
' - "注記" # equiv of "Note" in Japanese\n'
' - "caution"\n'
' - "注意" # equiv. of "Caution" in Japanese\n'
' - "warning"\n'
' - "警告" # equiv. of "Warning" in Japanese\n'
'\n'
'Any paragraph that starts with a bold or italic '
'section that consists of only one of the listed '
'words triggers a callout. The callout has two '
'CSS classes:\n'
'\n'
'A general callout class. This is dactyl-callout '
'by default.\n'
'The word that triggered the callout (for '
'example, tip) in all lowercase.\n'
'\n'
'You can customize the general callout class with '
'a config file line such as the following:\n'
'callout_class: "my-callout-class"\n'
'\n'
'Finally, add the relevant CSS styles to your '
'stylesheet for the new class. For example, the '
'default Dactyl stylesheet defines the "Tip" and '
'"ヒント" callout styles as follows:\n'
'.dactyl-content .dactyl-callout {\n'
' border-style: solid;\n'
' border-radius: .25rem;\n'
' border-width: 1px;\n'
' border-left-width: 1px;\n'
' border-left-width: 4px;\n'
' padding: 5px;\n'
' padding-left: 5px;\n'
' padding-left: 25px;\n'
' page-break-inside: avoid;\n'
'}\n'
'\n'
'.dactyl-content .dactyl-callout.tip, '
'.dactyl-content .dactyl-callout.ヒント {\n'
' border-color: #28a745; /* Green border */\n'
'}\n'
'\n'
'.dactyl-content .dactyl-callout.tip > '
'strong:first-child::before,\n'
'.dactyl-content .dactyl-callout.tip > p '
'strong:first-child::before,\n'
'.dactyl-content .dactyl-callout.ヒント > '
'strong:first-child::before,\n'
'.dactyl-content .dactyl-callout.ヒント > p '
'strong:first-child::before {\n'
' content: "\\f058"; /* fontawesome '
'check-circle icon */\n'
' font-family: FontAwesome;\n'
' color: #28a745;\n'
' margin-left: -20px;\n'
' padding-right: 5px;\n'
'}\n',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything', 'filterdemos']},
{'__dactyl_provided_filename__': True,
'blurb': 'Intelligent cross-references are a feature designed '
'to be a link when they can be, and text directing '
"people to a different target (guide) if not. Here's "
'some examples for testing:',
'category': 'Filters',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers', 'xrefs'],
'foo': 'fooooooo',
'headermap': {'Anchors¶': '#anchors',
'Intelligent Cross-References¶': '#intelligent-cross-references'},
'hover_anchors': '¶',
'html': 'xrefs.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a8b0>,
'md': 'filters/xrefs.md',
'name': 'Intelligent Cross-References',
'parent': 'filters.html',
'plaintext': 'Intelligent Cross-References¶\n'
'Intelligent cross-references are a feature '
'designed to be a link when they can be, and text '
'directing people to a different target (guide) '
"if not. Here's some examples for testing:\n"
'You can link by HTML filename: \n'
'Or by MD filename: \n'
'If the MD filename is ambiguous, you can specify '
'the full path:\n'
'\n'
'For an example of an inline cross reference, see '
'.\n'
'Also, demonstrating that context, spaces, and '
"case mostly don't matter:\n"
'\n'
'\n'
'(Above this should be a cross-reference to the '
'includes test.)\n'
'\n'
'Anchors¶\n'
'You can use anchors but the generated labels '
'always use the page name: \n'
'If you want to refer to a specific anchor, the '
'workaround is to use an explicit label: Code '
'Blocks\n'
'If the cross-reference appears in multiple '
'targets, Dactyl chooses the first such target '
'listed for the file. For example, if you want to '
'refer to the Conditionals page using the '
'conditionals target (when linking it from the '
'filterexamples target), you have to change the '
'order listed in the config file. Dactyl will '
'always use the "everything" target since that\'s '
'the first one listed:\n'
'\n'
'If you want to specify a different target, you '
'have to use conditional text in Jinja templating '
'syntax instead of smart xrefs.',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything', 'filterdemos']},
{'__dactyl_provided_filename__': True,
'blurb': 'The buttonize filter makes some links look like '
'buttons if their link text ends in a > sign.',
'category': 'Filters',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers', 'buttonize'],
'foo': 'fooooooo',
'headermap': {'Buttonize Filter¶': '#buttonize-filter'},
'hover_anchors': '¶',
'html': 'buttonize.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a940>,
'md': 'filters/buttonize.md',
'name': 'Buttonize Filter',
'parent': 'filters.html',
'plaintext': 'Buttonize Filter¶\n'
'The buttonize filter makes some links look like '
'buttons if their link text ends in a > sign.\n'
'Markdown:\n'
'[Normal Link](https://github.com/ripple/dactyl)\n'
'\n'
'[Button Link '
'>](http://github.com/ripple/dactyl)\n'
'\n'
'Results:\n'
'Normal Link\n'
'Button Link >',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything', 'filterdemos']},
{'__dactyl_provided_filename__': True,
'blurb': 'Uses shields.io to make badges out of links. For '
'example:',
'category': 'Filters',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers', 'badges'],
'foo': 'fooooooo',
'headermap': {'Badges¶': '#badges'},
'hover_anchors': '¶',
'html': 'badges.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a9d0>,
'md': 'filters/badges.md',
'name': 'Badges',
'parent': 'filters.html',
'plaintext': 'Badges¶\n'
'Uses shields.io to make badges out of links. For '
'example:\n'
'[badge: orange](http://example.com/ '
'"BADGE_ORANGE")\n'
'\n'
'Results in a badge like this:\n'
'badge: orange\n'
'To make a badge, create a link whose label is '
'leftside: rightside (separated by a colon (:) '
"character) and set the link's title text to "
'"BADGE_(COLOR)" (all-caps) where "(COLOR)" is '
'one of the following:\n'
'\n'
'BRIGHTGREEN\n'
'GREEN\n'
'YELLOWGREEN\n'
'YELLOW\n'
'ORANGE\n'
'RED\n'
'LIGHTGREY\n'
'BLUE\n'
'Any 6-digit hexadecimal color code. For example, '
'BADGE_006633 for Color:006633\n',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything', 'filterdemos']},
{'__dactyl_provided_filename__': True,
'blurb': 'The multi code-tabs filter lets you list multiple '
'code samples and have them appear as tabs in the '
'HTML version. It looks like this:',
'category': 'Filters',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers', 'multicode_tabs'],
'foo': 'fooooooo',
'headermap': {'Multi Code-Tabs Filter¶': '#multi-code-tabs-filter',
'Syntax¶': '#syntax',
'With Custom Templates¶': '#with-custom-templates'},
'hover_anchors': '¶',
'html': 'multicode_tabs.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33aa60>,
'md': 'filters/multicode_tabs.md',
'name': 'Multi Code-Tabs Filter',
'parent': 'filters.html',
'plaintext': 'Multi Code-Tabs Filter¶\n'
'The multi code-tabs filter lets you list '
'multiple code samples and have them appear as '
'tabs in the HTML version. It looks like this:\n'
'\n'
'Tab 1 Name\n'
'{\n'
' "id": 2,\n'
' "command": "account_info",\n'
' "account": '
'"r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",\n'
' "strict": true,\n'
' "ledger_index": "validated"\n'
'}\n'
'\n'
'Tab 2 Name\n'
'POST http://s1.ripple.com:51234/\n'
'{\n'
' "method": "account_info",\n'
' "params": [\n'
' {\n'
' "account": '
'"r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",\n'
' "strict": true,\n'
' "ledger_index": "validated"\n'
' }\n'
' ]\n'
'}\n'
'\n'
'Tab 3 Name\n'
'rippled account_info '
'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59 validated '
'true\n'
'\n'
'\n'
'Syntax¶\n'
'To display code in tabs, use the following '
'syntax:\n'
'<!-- MULTICODE_BLOCK_START -->\n'
'\n'
'_First Tab Name_\n'
'\n'
'```js\n'
'console.log("First tab contents");\n'
'```\n'
'\n'
'_Second Tab Name_\n'
'\n'
'```py\n'
'print("Second tab contents")\n'
'```\n'
'\n'
'<!-- MULTICODE_BLOCK_END -->\n'
'\n'
'There is no hard limit on the number of tabs you '
'can have. If the total width of the tab names '
'gets too long for the viewscreen, they get '
'broken into multiple lines, which may not look '
'that good depending on your CSS.\n'
'Tabs can only contain code blocks, not other '
'contents.\n'
'With Custom Templates¶\n'
'These tabs require some CSS and JavaScript to '
'work:\n'
'\n'
'multicode_tabs.js\n'
'dactyl-multicode_tabs.css\n'
'\n'
"If you're writing your own templates, you need "
'to include these lines of code in your project '
"to get the tabs to display properly. If you're "
'using the built-in templates, they load this '
"code automatically, so you don't need to do "
'anything special.',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything', 'filterdemos']},
{'__dactyl_provided_filename__': True,
'blurb': 'This filter adds an "external link" icon to links to '
"outside websites. Well, it's not actually all that "
"smart. It doesn't know what website it's on, so it "
'adds the icon to any link whose URL starts with '
'http: or https:. It also sets all external links to '
'open in a new tab/window.',
'category': 'Filters',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers', 'buttonize', 'external_links'],
'foo': 'fooooooo',
'headermap': {'External Links¶': '#external-links'},
'hover_anchors': '¶',
'html': 'external_links.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33aaf0>,
'md': 'filters/external_links.md',
'name': 'External Links',
'parent': 'filters.html',
'plaintext': 'External Links¶\n'
'This filter adds an "external link" icon to '
"links to outside websites. Well, it's not "
"actually all that smart. It doesn't know what "
"website it's on, so it adds the icon to any link "
'whose URL starts with http: or https:. It also '
'sets all external links to open in a new '
'tab/window.\n'
"A link to another page won't have the icon.\n"
'If you try to combine this filter with the '
'button links filter >, make sure buttonize runs '
'first. Otherwise, external links will not get '
'styled as buttons when intended.',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything', 'filterdemos']}],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Filters¶': '#filters'},
'hover_anchors': '¶',
'html': 'filters.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a790>,
'md': 'filters/filters.md',
'name': 'Filters',
'parent': 'index.html',
'plaintext': 'Filters¶\n'
'Dactyl supports additional custom post-processing through the '
'use of filters which are essentially custom plugins. Filters '
"can operate on the markdown (after it's been pre-processed), "
"on the raw HTML (after it's been parsed), or on a "
'BeautifulSoup object representing the output HTML. Filters can '
'also export functions and values that are available to the '
'preprocessor.\n'
'Dactyl comes with several filters, which you can enable in '
'your config file. You can also write your own filters. If you '
'do, you must specify the paths to the folder(s) containing '
'your filter files in the filter_paths array of the config '
'file.\n'
'To enable a filter for a target or page, set the filters field '
'of the config to be an array of filter names, where the filter '
'names are derived from the Python source files in the format '
'filter_<filtername>.py. Filter names must be valid Python '
"variable names, so they can't start with a numeral and must "
'contain only alphanumeric and underscore characters.\n'
'Dactyl automatically runs the following functions from filter '
"files (skipping any that aren't defined):\n"
'\n'
'Before running the preprocessor on a page, Dactyl adds all '
"items from each filter's export global dictionary to the "
'preprocessor environment.\n'
'Dactyl runs the filter_markdown(md, **kwargs) function of each '
'filter after the preprocessor. This function receives the '
'preprocessed markdown as a string in the md argument and must '
'return a string with the markdown as filtered.\n'
'Dactyl runs the filter_html(html, **kwargs) function after the '
'markdown processor. This function receives the parsed markdown '
'content as an HTML string in the html argument and must return '
'a string with the HTML as filtered.\n'
'Dactyl runs the filter_soup(soup, **kwargs) function after the '
'HTML filters. This function is expected to directly modify the '
'soup argument, which contains a BeautifulSoup 4 object '
'representing the HTML contents.\n'
'\n'
'The keyword arguments (**kwargs) for the functions may change '
'in future versions. As of Dactyl 0.5.0, the arguments are as '
'follows:\n'
'\n'
'\n'
'\n'
'Field\n'
'Type\n'
'Description\n'
'\n'
'\n'
'\n'
'\n'
'currentpage\n'
'Dict\n'
'The current page, as defined in the config file plus values '
'inherited from the current target and any processing or '
'calculations. (For example, Dactyl automatically adds a name '
"field if one isn't present.)\n"
'\n'
'\n'
'categories\n'
'List\n'
'A de-duplicated, ordered list of category fields present among '
'pages in this target.\n'
'\n'
'\n'
'pages\n'
'List\n'
'A list of page objects for all pages in the current target, in '
'the same order they appear in the config file.\n'
'\n'
'\n'
'target\n'
'Dict\n'
'The current target definition, as derived from the config '
'file.\n'
'\n'
'\n'
'current_time\n'
'String\n'
'The time this build was started. The format is defined by your '
"config's global time_format field (in stftime format), "
'defaulting to YYYY-MM-DD.\n'
'\n'
'\n'
'mode\n'
'String\n'
'Either html, pdf, or md depending on what output Dactyl is '
'building.\n'
'\n'
'\n'
'config\n'
'Dict\n'
'The global config object, based on the config file plus any '
'commandline switches.\n'
'\n'
'\n'
'logger\n'
'Logger\n'
'The logging object Dactyl uses, with the verbosity set to '
'match user input.\n'
'\n'
'\n',
'section_header': True,
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything', 'filterdemos'],
'template': 'landing.html'},
{'__dactyl_provided_filename__': True,
'blurb': 'Callouts are a specially-colored blocks that call attention to '
'particular bits of information. They might be special warnings, '
'asides, or other details. To use callouts, the page (or target) '
'has to have the callouts filter enabled, then provide syntax such '
'as the following:',
'category': 'Filters',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers', 'callouts'],
'foo': 'fooooooo',
'headermap': {'Callouts Demonstration¶': '#callouts-demonstration',
'Cases to Avoid¶': '#cases-to-avoid',
'Custom Callout Types¶': '#custom-callout-types',
'Multiline Callouts¶': '#multiline-callouts'},
'hover_anchors': '¶',
'html': 'callouts.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a820>,
'md': 'filters/callouts.md',
'name': 'Callouts Demonstration',
'parent': 'filters.html',
'plaintext': 'Callouts Demonstration¶\n'
'Callouts are a specially-colored blocks that call attention to '
'particular bits of information. They might be special '
'warnings, asides, or other details. To use callouts, the page '
'(or target) has to have the callouts filter enabled, then '
'provide syntax such as the following:\n'
'**Tip:** This is a "Tip" callout, styled with green and a '
'checkmark by default.\n'
'\n'
'Tip: This is a "Tip" callout, styled with green and a '
'checkmark by default.\n'
'Note: Callouts have four types by default: "Note", "Tip", '
'"Caution", and "Warning".\n'
'Caution: Be sure not to overuse callouts.\n'
'Warning: Callouts are very specific. **Note:** triggers a '
"callout; **Notes:** doesn't. The colon is optional, though.\n"
'Multiline Callouts¶\n'
'\n'
'Tip: Multiline callouts with blockquotes are now possible.\n'
'\n'
'Do this to include bulleted lists.\n'
'Or other types of lists.\n'
'\n'
'\n'
'\n'
'Code example:\n'
'> **Tip:** Multiline callouts with blockquotes are now '
'possible.\n'
'>\n'
'> - Do this to include bulleted lists.\n'
'> - Or other types of lists.\n'
'>\n'
'\n'
'If you have a callout word like tip bolded mid-paragraph, it '
'should not become a callout.\n'
'\n'
'Please note that this also applies to blockquotes.\n'
'\n'
'There is a difficult edge case for blockquotes where a '
'paragraph other than the first one starts with a callout '
'keyword:\n'
'\n'
'This is the start of a blockquote that is not, itself, a '
'callout.\n'
'Note: This callout occurs in the middle of a blockquote.\n'
'But the blockquote containing it is not, itself, a callout.\n'
'\n'
'Also, note that you can cannot use code fences in '
'blockquotes.\n'
'\n'
"Caution: Code fences in blockquotes don't work right.\n"
'js\n'
'if (true) {\n'
" console.log('this line of code should be indented');\n"
'}\n'
'The code fence gets treated as inlined code text instead. This '
'is a limitation of Python-Markdown.\n'
'\n'
'You can, however, use indented code blocks in blockquotes:\n'
'\n'
'Tip: To get a proper code block in a blockquote, provide a '
'single\n'
'line of just the blockquote intro >, and indent the code block '
'5 spaces.\n'
'print("Hello world!")\n'
'if True:\n'
' print("Note that extra spaces beyond the initial 5 carry '
'over.")\n'
'\n'
'To continue the block quote afterwords, leave a near-blank '
'line similarly.\n'
"Do not use code fences in a blockquote: they don't work as "
'expected.\n'
'\n'
'Cases to Avoid¶\n'
'\n'
'In a list, the callout applies to the whole list item.\n'
'Tip: You can have callouts nested in a list.\n'
"Warning: You probably wouldn't like what happens if you nest "
'callouts in list items that are already callouts.\n'
'\n'
'\n'
'\n'
'\n'
"One more point. Note: The callout doesn't trigger if it's not "
'at the start of the element.\n'
'\n'
'\n'
'\n'
'\n'
'Table\n'
'Stuff\n'
'\n'
'\n'
'\n'
'\n'
'Warning: Callout syntax in table cells is weird.\n'
"So it's probably best not to do that.\n"
'\n'
'\n'
'Probably.\n'
'Caution: It could maybe work better with better CSS.\n'
'\n'
'\n'
'\n'
'Custom Callout Types¶\n'
'You can define additional callout types if you want. This '
'requires two pieces:\n'
'\n'
'A list of what words should trigger a callout.\n'
'CSS styles for the relevant callout types.\n'
'\n'
'To define custom callout classes, write the trigger words '
"(case-insensitive) in your project's Dactyl config file. This "
'overwrites the default list, so include the default four if '
'you still want to use them. For example:\n'
'callout_types:\n'
' - "tip"\n'
' - "ヒント" # equiv. of "Tip" in Japanese (lit. "Hint")\n'
' - "note"\n'
' - "注記" # equiv of "Note" in Japanese\n'
' - "caution"\n'
' - "注意" # equiv. of "Caution" in Japanese\n'
' - "warning"\n'
' - "警告" # equiv. of "Warning" in Japanese\n'
'\n'
'Any paragraph that starts with a bold or italic section that '
'consists of only one of the listed words triggers a callout. '
'The callout has two CSS classes:\n'
'\n'
'A general callout class. This is dactyl-callout by default.\n'
'The word that triggered the callout (for example, tip) in all '
'lowercase.\n'
'\n'
'You can customize the general callout class with a config file '
'line such as the following:\n'
'callout_class: "my-callout-class"\n'
'\n'
'Finally, add the relevant CSS styles to your stylesheet for '
'the new class. For example, the default Dactyl stylesheet '
'defines the "Tip" and "ヒント" callout styles as follows:\n'
'.dactyl-content .dactyl-callout {\n'
' border-style: solid;\n'
' border-radius: .25rem;\n'
' border-width: 1px;\n'
' border-left-width: 1px;\n'
' border-left-width: 4px;\n'
' padding: 5px;\n'
' padding-left: 5px;\n'
' padding-left: 25px;\n'
' page-break-inside: avoid;\n'
'}\n'
'\n'
'.dactyl-content .dactyl-callout.tip, .dactyl-content '
'.dactyl-callout.ヒント {\n'
' border-color: #28a745; /* Green border */\n'
'}\n'
'\n'
'.dactyl-content .dactyl-callout.tip > '
'strong:first-child::before,\n'
'.dactyl-content .dactyl-callout.tip > p '
'strong:first-child::before,\n'
'.dactyl-content .dactyl-callout.ヒント > '
'strong:first-child::before,\n'
'.dactyl-content .dactyl-callout.ヒント > p '
'strong:first-child::before {\n'
' content: "\\f058"; /* fontawesome check-circle icon */\n'
' font-family: FontAwesome;\n'
' color: #28a745;\n'
' margin-left: -20px;\n'
' padding-right: 5px;\n'
'}\n',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything', 'filterdemos']},
{'__dactyl_provided_filename__': True,
'blurb': 'Intelligent cross-references are a feature designed to be a link '
'when they can be, and text directing people to a different target '
"(guide) if not. Here's some examples for testing:",
'category': 'Filters',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers', 'xrefs'],
'foo': 'fooooooo',
'headermap': {'Anchors¶': '#anchors',
'Intelligent Cross-References¶': '#intelligent-cross-references'},
'hover_anchors': '¶',
'html': 'xrefs.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a8b0>,
'md': 'filters/xrefs.md',
'name': 'Intelligent Cross-References',
'parent': 'filters.html',
'plaintext': 'Intelligent Cross-References¶\n'
'Intelligent cross-references are a feature designed to be a '
'link when they can be, and text directing people to a '
"different target (guide) if not. Here's some examples for "
'testing:\n'
'You can link by HTML filename: \n'
'Or by MD filename: \n'
'If the MD filename is ambiguous, you can specify the full '
'path:\n'
'\n'
'For an example of an inline cross reference, see .\n'
'Also, demonstrating that context, spaces, and case mostly '
"don't matter:\n"
'\n'
'\n'
'(Above this should be a cross-reference to the includes '
'test.)\n'
'\n'
'Anchors¶\n'
'You can use anchors but the generated labels always use the '
'page name: \n'
'If you want to refer to a specific anchor, the workaround is '
'to use an explicit label: Code Blocks\n'
'If the cross-reference appears in multiple targets, Dactyl '
'chooses the first such target listed for the file. For '
'example, if you want to refer to the Conditionals page using '
'the conditionals target (when linking it from the '
'filterexamples target), you have to change the order listed in '
'the config file. Dactyl will always use the "everything" '
"target since that's the first one listed:\n"
'\n'
'If you want to specify a different target, you have to use '
'conditional text in Jinja templating syntax instead of smart '
'xrefs.',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything', 'filterdemos']},
{'__dactyl_provided_filename__': True,
'blurb': 'The buttonize filter makes some links look like buttons if their '
'link text ends in a > sign.',
'category': 'Filters',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers', 'buttonize'],
'foo': 'fooooooo',
'headermap': {'Buttonize Filter¶': '#buttonize-filter'},
'hover_anchors': '¶',
'html': 'buttonize.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a940>,
'md': 'filters/buttonize.md',
'name': 'Buttonize Filter',
'parent': 'filters.html',
'plaintext': 'Buttonize Filter¶\n'
'The buttonize filter makes some links look like buttons if '
'their link text ends in a > sign.\n'
'Markdown:\n'
'[Normal Link](https://github.com/ripple/dactyl)\n'
'\n'
'[Button Link >](http://github.com/ripple/dactyl)\n'
'\n'
'Results:\n'
'Normal Link\n'
'Button Link >',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything', 'filterdemos']},
{'__dactyl_provided_filename__': True,
'blurb': 'Uses shields.io to make badges out of links. For example:',
'category': 'Filters',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers', 'badges'],
'foo': 'fooooooo',
'headermap': {'Badges¶': '#badges'},
'hover_anchors': '¶',
'html': 'badges.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33a9d0>,
'md': 'filters/badges.md',
'name': 'Badges',
'parent': 'filters.html',
'plaintext': 'Badges¶\n'
'Uses shields.io to make badges out of links. For example:\n'
'[badge: orange](http://example.com/ "BADGE_ORANGE")\n'
'\n'
'Results in a badge like this:\n'
'badge: orange\n'
'To make a badge, create a link whose label is leftside: '
'rightside (separated by a colon (:) character) and set the '
'link\'s title text to "BADGE_(COLOR)" (all-caps) where '
'"(COLOR)" is one of the following:\n'
'\n'
'BRIGHTGREEN\n'
'GREEN\n'
'YELLOWGREEN\n'
'YELLOW\n'
'ORANGE\n'
'RED\n'
'LIGHTGREY\n'
'BLUE\n'
'Any 6-digit hexadecimal color code. For example, BADGE_006633 '
'for Color:006633\n',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything', 'filterdemos']},
{'__dactyl_provided_filename__': True,
'blurb': 'The multi code-tabs filter lets you list multiple code samples and '
'have them appear as tabs in the HTML version. It looks like this:',
'category': 'Filters',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers', 'multicode_tabs'],
'foo': 'fooooooo',
'headermap': {'Multi Code-Tabs Filter¶': '#multi-code-tabs-filter',
'Syntax¶': '#syntax',
'With Custom Templates¶': '#with-custom-templates'},
'hover_anchors': '¶',
'html': 'multicode_tabs.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33aa60>,
'md': 'filters/multicode_tabs.md',
'name': 'Multi Code-Tabs Filter',
'parent': 'filters.html',
'plaintext': 'Multi Code-Tabs Filter¶\n'
'The multi code-tabs filter lets you list multiple code samples '
'and have them appear as tabs in the HTML version. It looks '
'like this:\n'
'\n'
'Tab 1 Name\n'
'{\n'
' "id": 2,\n'
' "command": "account_info",\n'
' "account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",\n'
' "strict": true,\n'
' "ledger_index": "validated"\n'
'}\n'
'\n'
'Tab 2 Name\n'
'POST http://s1.ripple.com:51234/\n'
'{\n'
' "method": "account_info",\n'
' "params": [\n'
' {\n'
' "account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",\n'
' "strict": true,\n'
' "ledger_index": "validated"\n'
' }\n'
' ]\n'
'}\n'
'\n'
'Tab 3 Name\n'
'rippled account_info r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59 '
'validated true\n'
'\n'
'\n'
'Syntax¶\n'
'To display code in tabs, use the following syntax:\n'
'<!-- MULTICODE_BLOCK_START -->\n'
'\n'
'_First Tab Name_\n'
'\n'
'```js\n'
'console.log("First tab contents");\n'
'```\n'
'\n'
'_Second Tab Name_\n'
'\n'
'```py\n'
'print("Second tab contents")\n'
'```\n'
'\n'
'<!-- MULTICODE_BLOCK_END -->\n'
'\n'
'There is no hard limit on the number of tabs you can have. If '
'the total width of the tab names gets too long for the '
'viewscreen, they get broken into multiple lines, which may not '
'look that good depending on your CSS.\n'
'Tabs can only contain code blocks, not other contents.\n'
'With Custom Templates¶\n'
'These tabs require some CSS and JavaScript to work:\n'
'\n'
'multicode_tabs.js\n'
'dactyl-multicode_tabs.css\n'
'\n'
"If you're writing your own templates, you need to include "
'these lines of code in your project to get the tabs to display '
"properly. If you're using the built-in templates, they load "
"this code automatically, so you don't need to do anything "
'special.',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything', 'filterdemos']},
{'__dactyl_provided_filename__': True,
'blurb': 'This filter adds an "external link" icon to links to outside '
"websites. Well, it's not actually all that smart. It doesn't know "
"what website it's on, so it adds the icon to any link whose URL "
'starts with http: or https:. It also sets all external links to '
'open in a new tab/window.',
'category': 'Filters',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers', 'buttonize', 'external_links'],
'foo': 'fooooooo',
'headermap': {'External Links¶': '#external-links'},
'hover_anchors': '¶',
'html': 'external_links.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33aaf0>,
'md': 'filters/external_links.md',
'name': 'External Links',
'parent': 'filters.html',
'plaintext': 'External Links¶\n'
'This filter adds an "external link" icon to links to outside '
"websites. Well, it's not actually all that smart. It doesn't "
"know what website it's on, so it adds the icon to any link "
'whose URL starts with http: or https:. It also sets all '
'external links to open in a new tab/window.\n'
"A link to another page won't have the icon.\n"
'If you try to combine this filter with the button links filter '
'>, make sure buttonize runs first. Otherwise, external links '
'will not get styled as buttons when intended.',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything', 'filterdemos']},
{'blurb': 'Dactyl is designed to be customized and extended to each '
"individual project's needs. These pages demonstrate some ways you "
'can extend Dactyl.',
'category': 'Extending',
'children': [{'__dactyl_provided_filename__': True,
'blurb': 'Dactyl provides built-in templates that are fairly '
'full-featured, but you can also write your own, '
'including ones that extent or repurpose parts of the '
'built-in templates, and get updates automatically '
'when Dactyl is updated. As an example, this page '
'uses a custom template that addsa "related pages" '
'module to the right-hand sidebar.',
'category': 'Extending',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Built-In Templates¶': '#built-in-templates',
'Children Module¶': '#children-module',
'Module Templates¶': '#module-templates',
'Page Templates¶': '#page-templates',
'Template Data¶': '#template-data',
'Templates¶': '#templates',
'Tree Nav Module¶': '#tree-nav-module'},
'hover_anchors': '¶',
'html': 'templates.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33ac10>,
'md': 'extending/templates.md',
'name': 'Templates',
'parent': 'extending-index.html',
'plaintext': 'Templates¶\n'
'Dactyl provides built-in templates that are '
'fairly full-featured, but you can also write '
'your own, including ones that extent or '
'repurpose parts of the built-in templates, and '
'get updates automatically when Dactyl is '
'updated. As an example, this page uses a custom '
'template that addsa "related pages" module to '
'the right-hand sidebar.\n'
'Built-In Templates¶\n'
'Many of the built-in templates work better if '
'you set certain fields on your target or page '
"definitions. Here's a list of those fields:\n"
'\n'
'\n'
'\n'
'Field\n'
'Description\n'
'\n'
'\n'
'\n'
'\n'
'prefix\n'
'The base path for this site. Use / for a site '
'served from the top-level of its domain. '
'Required for navigation if your site has '
'subfolders or "pretty URLs".\n'
'\n'
'\n'
'logo\n'
'URL or path for a logo image to use in the '
'top-left. If not defined, uses a text header '
'instead.\n'
'\n'
'\n'
'google_analytics_tag\n'
'String tag to use with Google Analytics, e.g. '
'"UA-00000000-0". If not defined, doesn\'t load '
'Google Analytics.\n'
'\n'
'\n'
'repository\n'
"URL to this site's source repository on GitHub. "
'Required for the "Edit on GitHub" button.\n'
'\n'
'\n'
'url\n'
'The fully-qualified URL for the base of the '
'site. Required by the sitemap and Google Search '
'templates.\n'
'\n'
'\n'
'stylesheet\n'
'URL or path to the default stylesheet. The '
'default includes Bootstrap 4.5 as well as custom '
'CSS for code tabs, callouts, and the page '
'layout. See the styles dir for the source SCSS. '
'The default is served by dactyl.link.\n'
'\n'
'\n'
'dactyljs\n'
'URL or path to the Dactyl JavaScript file to '
'use. This defines "jump to top" and code tab '
'behavior. The default is served by dactyl.link.\n'
'\n'
'\n'
'bootstrapjs\n'
'URL or path to the Bootstrap JavaScript file to '
'use. The default is served by BootstrapCDN.\n'
'\n'
'\n'
'fontawesomecss\n'
'URL or path to FontAwesome (v4) CSS file to use. '
'The default is served by BootstrapCDN.\n'
'\n'
'\n'
'\n'
'Page Templates¶\n'
'The following built-in templates represent full '
'pages, so you can use them with the '
'default_template: and template: settings in the '
'config file or frontmatter. You can also derive '
'your own templates from these templates using {% '
"extends 'template' %} syntax.\n"
'\n'
'\n'
'\n'
'Template\n'
'Description\n'
'\n'
'\n'
'\n'
'\n'
'404.html\n'
'Contains an error message intended to be used as '
'a custom 404 page.\n'
'\n'
'\n'
'base.html\n'
'A general purpose template with a 3-column '
'layout, fixed header, and a footer. The '
'navigation uses the hierarchy (parent and child) '
'fields introduced by Dactyl v0.10.0. This uses '
'Bootstrap 4.5.0. Most of the other built-in '
'templates are derived from this template.\n'
'\n'
'\n'
'doc.html\n'
'Specialized for individual documents. This is '
'the new default template. The right sidebar has '
'an in-page table of contents, and this runs code '
'tab and syntax highlighting JavaScript by '
'default. (You still need to enable the '
'multicode_tabs filter in your dactyl-config.yml '
'file to get code tab syntax.)\n'
'\n'
'\n'
'landing.html\n'
'A landing page that displays a list of child '
'pages in the center column.\n'
'\n'
'\n'
'pdf-cover.html\n'
'A cover page and table of contents for PDFs.\n'
'\n'
'\n'
'redirect.html\n'
'Redirects the user to another URL, as set by the '
"page's redirect_url field. Useful for "
'deprecating pages.\n'
'\n'
'\n'
'simple.html\n'
'A minimal template with no dependencies.\n'
'\n'
'\n'
'template-sitemap.txt\n'
'A template for a text sitemap for use by search '
'engines.\n'
'\n'
'\n'
'\n'
'When extending the default templates, you many '
'of them have blocks you can replace. For the '
'full list, see the templates directly.\n'
'Module Templates¶\n'
'The following built-in templates are partial '
'modules you can use with {% include '
"'templatehere.html' %} blocks from other "
'templates. Many of these pieces are used by the '
'page templates above, as well:\n'
'\n'
'\n'
'\n'
'Template\n'
'Description\n'
'\n'
'\n'
'\n'
'\n'
'algolia-docsearch.html\n'
'Provides a search box (and accompanying '
'resources) powered by Algolia DocSearch. To use '
'this, you must provide your Algolia API key in '
"the target's algolia_api_key field provide your "
"index name in the target's algolia_index_name "
'field.\n'
'\n'
'\n'
'breadcrumbs.html\n'
'Provides breadcrumbs to the current page, based '
'on the hierarchy fields.\n'
'\n'
'\n'
'children.html\n'
'Displays a bulleted list of children of the '
'current page. You can modify the behavior by '
'setting certain properties before including this '
'template. (See below for an example.)\n'
'\n'
'\n'
'footer.html\n'
'A footer containing a copyright notice, license '
'link, and language selector (if you have the '
'right fields defined).\n'
'\n'
'\n'
'github-edit.html\n'
"A button that links to edit the current page's "
"source file on GitHub. Requires the target's "
"repository field to be the URL of the site's "
'repository on GitHub.\n'
'\n'
'\n'
'header.html\n'
'A fixed header containing a logo, navigation to '
'top-level pages, search, and Edit on GitHub '
'buttons if the right fields are defined.\n'
'\n'
'\n'
'language-dropdown.html\n'
'A language-selector dropdown that points to the '
'equivalent page in other languages, if you have '
'multiple languages defined. (This is the one '
'used in the header.)\n'
'\n'
'\n'
'language-dropdown.html\n'
'A horizontal language selector that points to '
'the equivalent page in other languages, if you '
'have multiple languages defined. (This is the '
'one used in the footer.)\n'
'\n'
'\n'
'page-toc.html\n'
'A Bootstrap/ScrollSpy-ready table of contents '
"based on the headers in the current page's "
'Markdown contents.\n'
'\n'
'\n'
'tree-nav.html\n'
'Tree-style site navigation with collapsible '
'levels. You can set a custom page to be the '
'"top" of the tree to show only a subset of your '
'site. Otherwise it uses the first page (usually '
'the auto-provided cover page) as the top of the '
'tree. Set nav_omit: true on a page to hide that '
'page from this navigation.\n'
'\n'
'\n'
'\n'
'Children Module¶\n'
'The following demonstrates how to use the '
'children.html template to display a list of '
'children of a page (including links):\n'
"{ % set parent_html = 'some-parent.html' %}\n"
'{ % set show_blurbs = True %}\n'
'{ % set depth = 3 %}\n'
"{ % include 'children.html' %}\n"
'\n'
'You can omit any or all of the {% set ... %} '
'statements to use the defaults:\n'
'\n'
'\n'
'\n'
'Setting\n'
'Description\n'
'Default\n'
'\n'
'\n'
'\n'
'\n'
'parent_html\n'
"Which page's children to show. The HTML filename "
'of that page.\n'
'The current page.\n'
'\n'
'\n'
'show_blurbs\n'
"If True, add the child page's blurb attribute "
'next to its link.\n'
'False\n'
'\n'
'\n'
'depth\n'
'How many levels in the hierarchy to show below '
'the parent.\n'
'5\n'
'\n'
'\n'
'\n'
'Tree Nav Module¶\n'
'The following shows how to display a subset of '
'the tree nav (starting with the file '
'some_parent.html) instead of the full tree:\n'
"{ % set tree_top = pages|selectattr('html', "
"'defined_and_equalto', "
"'some_parent.html')|list|first %}\n"
"{ % include 'tree-nav.html' %}\n"
'\n'
'Template Data¶\n'
'Dactyl provides the following information to '
"templates, which you can access with Jinja's "
'templating syntax (e.g. {{ target.display_name '
'}}):\n'
'\n'
'\n'
'\n'
'Field\n'
'Value\n'
'\n'
'\n'
'\n'
'\n'
'target\n'
'The target definition of the current target.\n'
'\n'
'\n'
'pages\n'
'The array of page definitions in the current '
'target. Use this to generate navigation across '
"pages. (The default templates don't do this, but "
'you should.)\n'
'\n'
'\n'
'currentpage\n'
'The definition of the page currently being '
'rendered.\n'
'\n'
'\n'
'categories\n'
'A de-duplicated array of categories that are '
'used by at least one page in this target, sorted '
'in the order they first appear.\n'
'\n'
'\n'
'config\n'
'The global Dactyl config object.\n'
'\n'
'\n'
'content\n'
'The parsed HTML content of the page currently '
'being rendered.\n'
'\n'
'\n'
'current_time\n'
'The current date as of rendering. The format is '
'YYYY-MM-DD by default; you can also set the '
'time_format field to a custom stftime format '
'string.\n'
'\n'
'\n'
'mode\n'
'The output format: either html (default), pdf, '
'or md.\n'
'\n'
'\n'
'page_toc\n'
'A table of contents generated from the current '
"page's headers. Wrap this in a <ul> element.\n"
'\n'
'\n'
'sidebar_content\n'
'(Deprecated alias for page_toc.)\n'
'\n'
'\n',
'related_links': ['frontmatter.html', 'code-highlighting.html'],
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything'],
'template': 'template-extends.html'},
{'__dactyl_provided_filename__': True,
'blurb': "This page demonstrates how you can use Dactyl's "
'built-in hierarchy features to generate a table of '
'contents automatically.',
'category': 'Extending',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Hierarchy Demo¶': '#hierarchy-demo'},
'hover_anchors': '¶',
'html': 'hierarchy.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33aca0>,
'md': 'extending/hierarchy.md',
'name': 'Hierarchy Demo',
'parent': 'extending-index.html',
'plaintext': 'Hierarchy Demo¶\n'
"This page demonstrates how you can use Dactyl's "
'built-in hierarchy features to generate a table '
'of contents automatically.\n'
'Source:\n'
'<ul>\n'
'{% macro page_w_children(pg) %}\n'
' <li class="dactyl-toc-entry"><a href="{{ '
'pg.html }}">{{ pg.name }}</a></li>\n'
' {% if pg.children %}\n'
' <ul>\n'
' {% for child in pg.children %}\n'
' {{ page_w_children(child) }}\n'
' {% endfor %}\n'
' </ul>\n'
' {% endif %}\n'
'{% endmacro %}\n'
'\n'
'{% for page in pages %}\n'
' {% if page.parent is undefined %}\n'
' {{ page_w_children(page) }}\n'
' {% endif %}\n'
'{% endfor %}\n'
'</ul>\n'
'\n'
'Results:',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything'],
'template': 'template-hierarchy.html'},
{'blurb': 'This page demonstrates custom filters in Dactyl. In '
'"Metal Gear Solid 2", the la-li-lu-le-lo are an '
'organization who brainwash people to say '
'"la-li-lu-le-lo" instead of "la-li-lu-le-lo" when '
'speaking aloud, even among their compatriots.',
'category': 'Extending',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers', 'patriots'],
'foo': 'fooooooo',
'headermap': {'Custom Filter¶': '#custom-filter'},
'hover_anchors': '¶',
'html': 'filter-examples-patriots.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33ad30>,
'md': 'extending/patriots.md',
'name': 'Custom Filter',
'parent': 'extending-index.html',
'plaintext': 'Custom Filter¶\n'
'This page demonstrates custom filters in Dactyl. '
'In "Metal Gear Solid 2", the la-li-lu-le-lo are '
'an organization who brainwash people to say '
'"la-li-lu-le-lo" instead of "la-li-lu-le-lo" '
'when speaking aloud, even among their '
'compatriots.\n'
'This page should read normally in the markdown '
'source, but in the Dactyl output if the patriots '
'filter is enabled, all instances of the '
"la-li-lu-le-lo' name is replaced with "
'la-li-lu-le-lo.\n'
'If a custom filter name is satisfied by multiple '
'custom filter directories, or by a custom filter '
'and by a Dactyl built-in filter, the first '
'listed custom filter directory takes highest '
'preference, and the Dactyl built-in filters are '
'lowest preference. However, if importing a '
'filter fails (for example, due to a syntax '
'error), a lower-precedence filter with the same '
'name may be loaded instead.',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'blurb': 'This page demonstrates custom filters in Dactyl. In '
'"Metal Gear Solid 2", the La-Li-Lu-Le-Lo are an '
'organization who brainwash people to say '
'"la-li-lu-le-lo" instead of "La-Li-Lu-Le-Lo" when '
'speaking aloud, even among their comla-li-lu-le-lo.',
'category': 'Extending',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers', 'patriots2'],
'foo': 'fooooooo',
'headermap': {'Custom Filter¶': '#custom-filter'},
'hover_anchors': '¶',
'html': 'filter-examples-patriots2.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33adc0>,
'md': 'extending/patriots.md',
'name': 'Custom Filter 2',
'parent': 'extending-index.html',
'plaintext': 'Custom Filter¶\n'
'This page demonstrates custom filters in Dactyl. '
'In "Metal Gear Solid 2", the La-Li-Lu-Le-Lo are '
'an organization who brainwash people to say '
'"la-li-lu-le-lo" instead of "La-Li-Lu-Le-Lo" '
'when speaking aloud, even among their '
'comla-li-lu-le-lo.\n'
'This page should read normally in the markdown '
'source, but in the Dactyl output if the '
'la-li-lu-le-lo filter is enabled, all instances '
"of the La-Li-Lu-Le-Lo' name is replaced with "
'la-li-lu-le-lo.\n'
'If a custom filter name is satisfied by multiple '
'custom filter directories, or by a custom filter '
'and by a Dactyl built-in filter, the first '
'listed custom filter directory takes highest '
'preference, and the Dactyl built-in filters are '
'lowest preference. However, if importing a '
'filter fails (for example, due to a syntax '
'error), a lower-precedence filter with the same '
'name may be loaded instead.',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'__dactyl_provided_filename__': True,
'blurb': 'The include_code filter provides a function that can '
'make a code sample from a file, pulling in just '
'specific lines if desired.',
'category': 'Extending',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers', 'include_code'],
'foo': 'fooooooo',
'headermap': {'Code Includer¶': '#code-includer'},
'hover_anchors': '¶',
'html': 'include_code.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33ae50>,
'md': 'extending/include_code.md',
'name': 'Code Includer',
'parent': 'extending-index.html',
'plaintext': 'Code Includer¶\n'
'The include_code filter provides a function that '
'can make a code sample from a file, pulling in '
'just specific lines if desired.\n'
'Call it like so:\n'
'{{ include_code("sample_include.json", '
'lines="1,3,5-6", mark_disjoint=True) }}\n'
'\n'
'Sample:\n'
'{"line one": "here",\n'
'...\n'
'"third line": 3,\n'
'...\n'
' "line 5": "FIVE",\n'
'"six": 6\n'
'\n'
'One range:\n'
'"second line": true,\n'
'"third line": 3,\n'
' "4th line": [1,2,3,4],\n'
'\n'
'The whole file:\n'
'{"line one": "here",\n'
'"second line": true,\n'
'"third line": 3,\n'
' "4th line": [1,2,3,4],\n'
' "line 5": "FIVE",\n'
'"six": 6\n'
'}\n'
'\n'
'Custom separator string for disjoint lines:\n'
'{"line one": "here",\n'
'"second line": true,\n'
'... (line omitted)...\n'
' "4th line": [1,2,3,4],\n'
' "line 5": "FIVE",\n'
'"six": 6\n'
'}\n',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'category': 'Extending',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'hover_anchors': '¶',
'html': 'debug.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33aee0>,
'md': 'extending/debug.md',
'name': 'Debug',
'no_highlighting': True,
'parent': 'extending-index.html',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything'],
'template': 'template-minimal.html'}],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Extending Dactyl¶': '#extending-dactyl'},
'hover_anchors': '¶',
'html': 'extending-index.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33ab80>,
'md': 'extending/index.md',
'name': 'Extending Dactyl',
'parent': 'index.html',
'plaintext': 'Extending Dactyl¶\n'
'Dactyl is designed to be customized and extended to each '
"individual project's needs. These pages demonstrate some ways "
'you can extend Dactyl.',
'section_header': True,
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything'],
'template': 'landing.html'},
{'__dactyl_provided_filename__': True,
'blurb': 'Dactyl provides built-in templates that are fairly full-featured, '
'but you can also write your own, including ones that extent or '
'repurpose parts of the built-in templates, and get updates '
'automatically when Dactyl is updated. As an example, this page '
'uses a custom template that addsa "related pages" module to the '
'right-hand sidebar.',
'category': 'Extending',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Built-In Templates¶': '#built-in-templates',
'Children Module¶': '#children-module',
'Module Templates¶': '#module-templates',
'Page Templates¶': '#page-templates',
'Template Data¶': '#template-data',
'Templates¶': '#templates',
'Tree Nav Module¶': '#tree-nav-module'},
'hover_anchors': '¶',
'html': 'templates.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33ac10>,
'md': 'extending/templates.md',
'name': 'Templates',
'parent': 'extending-index.html',
'plaintext': 'Templates¶\n'
'Dactyl provides built-in templates that are fairly '
'full-featured, but you can also write your own, including ones '
'that extent or repurpose parts of the built-in templates, and '
'get updates automatically when Dactyl is updated. As an '
'example, this page uses a custom template that addsa "related '
'pages" module to the right-hand sidebar.\n'
'Built-In Templates¶\n'
'Many of the built-in templates work better if you set certain '
"fields on your target or page definitions. Here's a list of "
'those fields:\n'
'\n'
'\n'
'\n'
'Field\n'
'Description\n'
'\n'
'\n'
'\n'
'\n'
'prefix\n'
'The base path for this site. Use / for a site served from the '
'top-level of its domain. Required for navigation if your site '
'has subfolders or "pretty URLs".\n'
'\n'
'\n'
'logo\n'
'URL or path for a logo image to use in the top-left. If not '
'defined, uses a text header instead.\n'
'\n'
'\n'
'google_analytics_tag\n'
'String tag to use with Google Analytics, e.g. "UA-00000000-0". '
"If not defined, doesn't load Google Analytics.\n"
'\n'
'\n'
'repository\n'
"URL to this site's source repository on GitHub. Required for "
'the "Edit on GitHub" button.\n'
'\n'
'\n'
'url\n'
'The fully-qualified URL for the base of the site. Required by '
'the sitemap and Google Search templates.\n'
'\n'
'\n'
'stylesheet\n'
'URL or path to the default stylesheet. The default includes '
'Bootstrap 4.5 as well as custom CSS for code tabs, callouts, '
'and the page layout. See the styles dir for the source SCSS. '
'The default is served by dactyl.link.\n'
'\n'
'\n'
'dactyljs\n'
'URL or path to the Dactyl JavaScript file to use. This defines '
'"jump to top" and code tab behavior. The default is served by '
'dactyl.link.\n'
'\n'
'\n'
'bootstrapjs\n'
'URL or path to the Bootstrap JavaScript file to use. The '
'default is served by BootstrapCDN.\n'
'\n'
'\n'
'fontawesomecss\n'
'URL or path to FontAwesome (v4) CSS file to use. The default '
'is served by BootstrapCDN.\n'
'\n'
'\n'
'\n'
'Page Templates¶\n'
'The following built-in templates represent full pages, so you '
'can use them with the default_template: and template: settings '
'in the config file or frontmatter. You can also derive your '
"own templates from these templates using {% extends 'template' "
'%} syntax.\n'
'\n'
'\n'
'\n'
'Template\n'
'Description\n'
'\n'
'\n'
'\n'
'\n'
'404.html\n'
'Contains an error message intended to be used as a custom 404 '
'page.\n'
'\n'
'\n'
'base.html\n'
'A general purpose template with a 3-column layout, fixed '
'header, and a footer. The navigation uses the hierarchy '
'(parent and child) fields introduced by Dactyl v0.10.0. This '
'uses Bootstrap 4.5.0. Most of the other built-in templates are '
'derived from this template.\n'
'\n'
'\n'
'doc.html\n'
'Specialized for individual documents. This is the new default '
'template. The right sidebar has an in-page table of contents, '
'and this runs code tab and syntax highlighting JavaScript by '
'default. (You still need to enable the multicode_tabs filter '
'in your dactyl-config.yml file to get code tab syntax.)\n'
'\n'
'\n'
'landing.html\n'
'A landing page that displays a list of child pages in the '
'center column.\n'
'\n'
'\n'
'pdf-cover.html\n'
'A cover page and table of contents for PDFs.\n'
'\n'
'\n'
'redirect.html\n'
"Redirects the user to another URL, as set by the page's "
'redirect_url field. Useful for deprecating pages.\n'
'\n'
'\n'
'simple.html\n'
'A minimal template with no dependencies.\n'
'\n'
'\n'
'template-sitemap.txt\n'
'A template for a text sitemap for use by search engines.\n'
'\n'
'\n'
'\n'
'When extending the default templates, you many of them have '
'blocks you can replace. For the full list, see the templates '
'directly.\n'
'Module Templates¶\n'
'The following built-in templates are partial modules you can '
"use with {% include 'templatehere.html' %} blocks from other "
'templates. Many of these pieces are used by the page templates '
'above, as well:\n'
'\n'
'\n'
'\n'
'Template\n'
'Description\n'
'\n'
'\n'
'\n'
'\n'
'algolia-docsearch.html\n'
'Provides a search box (and accompanying resources) powered by '
'Algolia DocSearch. To use this, you must provide your Algolia '
"API key in the target's algolia_api_key field provide your "
"index name in the target's algolia_index_name field.\n"
'\n'
'\n'
'breadcrumbs.html\n'
'Provides breadcrumbs to the current page, based on the '
'hierarchy fields.\n'
'\n'
'\n'
'children.html\n'
'Displays a bulleted list of children of the current page. You '
'can modify the behavior by setting certain properties before '
'including this template. (See below for an example.)\n'
'\n'
'\n'
'footer.html\n'
'A footer containing a copyright notice, license link, and '
'language selector (if you have the right fields defined).\n'
'\n'
'\n'
'github-edit.html\n'
"A button that links to edit the current page's source file on "
"GitHub. Requires the target's repository field to be the URL "
"of the site's repository on GitHub.\n"
'\n'
'\n'
'header.html\n'
'A fixed header containing a logo, navigation to top-level '
'pages, search, and Edit on GitHub buttons if the right fields '
'are defined.\n'
'\n'
'\n'
'language-dropdown.html\n'
'A language-selector dropdown that points to the equivalent '
'page in other languages, if you have multiple languages '
'defined. (This is the one used in the header.)\n'
'\n'
'\n'
'language-dropdown.html\n'
'A horizontal language selector that points to the equivalent '
'page in other languages, if you have multiple languages '
'defined. (This is the one used in the footer.)\n'
'\n'
'\n'
'page-toc.html\n'
'A Bootstrap/ScrollSpy-ready table of contents based on the '
"headers in the current page's Markdown contents.\n"
'\n'
'\n'
'tree-nav.html\n'
'Tree-style site navigation with collapsible levels. You can '
'set a custom page to be the "top" of the tree to show only a '
'subset of your site. Otherwise it uses the first page (usually '
'the auto-provided cover page) as the top of the tree. Set '
'nav_omit: true on a page to hide that page from this '
'navigation.\n'
'\n'
'\n'
'\n'
'Children Module¶\n'
'The following demonstrates how to use the children.html '
'template to display a list of children of a page (including '
'links):\n'
"{ % set parent_html = 'some-parent.html' %}\n"
'{ % set show_blurbs = True %}\n'
'{ % set depth = 3 %}\n'
"{ % include 'children.html' %}\n"
'\n'
'You can omit any or all of the {% set ... %} statements to use '
'the defaults:\n'
'\n'
'\n'
'\n'
'Setting\n'
'Description\n'
'Default\n'
'\n'
'\n'
'\n'
'\n'
'parent_html\n'
"Which page's children to show. The HTML filename of that "
'page.\n'
'The current page.\n'
'\n'
'\n'
'show_blurbs\n'
"If True, add the child page's blurb attribute next to its "
'link.\n'
'False\n'
'\n'
'\n'
'depth\n'
'How many levels in the hierarchy to show below the parent.\n'
'5\n'
'\n'
'\n'
'\n'
'Tree Nav Module¶\n'
'The following shows how to display a subset of the tree nav '
'(starting with the file some_parent.html) instead of the full '
'tree:\n'
"{ % set tree_top = pages|selectattr('html', "
"'defined_and_equalto', 'some_parent.html')|list|first %}\n"
"{ % include 'tree-nav.html' %}\n"
'\n'
'Template Data¶\n'
'Dactyl provides the following information to templates, which '
"you can access with Jinja's templating syntax (e.g. {{ "
'target.display_name }}):\n'
'\n'
'\n'
'\n'
'Field\n'
'Value\n'
'\n'
'\n'
'\n'
'\n'
'target\n'
'The target definition of the current target.\n'
'\n'
'\n'
'pages\n'
'The array of page definitions in the current target. Use this '
'to generate navigation across pages. (The default templates '
"don't do this, but you should.)\n"
'\n'
'\n'
'currentpage\n'
'The definition of the page currently being rendered.\n'
'\n'
'\n'
'categories\n'
'A de-duplicated array of categories that are used by at least '
'one page in this target, sorted in the order they first '
'appear.\n'
'\n'
'\n'
'config\n'
'The global Dactyl config object.\n'
'\n'
'\n'
'content\n'
'The parsed HTML content of the page currently being rendered.\n'
'\n'
'\n'
'current_time\n'
'The current date as of rendering. The format is YYYY-MM-DD by '
'default; you can also set the time_format field to a custom '
'stftime format string.\n'
'\n'
'\n'
'mode\n'
'The output format: either html (default), pdf, or md.\n'
'\n'
'\n'
'page_toc\n'
"A table of contents generated from the current page's headers. "
'Wrap this in a <ul> element.\n'
'\n'
'\n'
'sidebar_content\n'
'(Deprecated alias for page_toc.)\n'
'\n'
'\n',
'related_links': ['frontmatter.html', 'code-highlighting.html'],
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything'],
'template': 'template-extends.html'},
{'__dactyl_provided_filename__': True,
'blurb': "This page demonstrates how you can use Dactyl's built-in hierarchy "
'features to generate a table of contents automatically.',
'category': 'Extending',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'headermap': {'Hierarchy Demo¶': '#hierarchy-demo'},
'hover_anchors': '¶',
'html': 'hierarchy.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33aca0>,
'md': 'extending/hierarchy.md',
'name': 'Hierarchy Demo',
'parent': 'extending-index.html',
'plaintext': 'Hierarchy Demo¶\n'
"This page demonstrates how you can use Dactyl's built-in "
'hierarchy features to generate a table of contents '
'automatically.\n'
'Source:\n'
'<ul>\n'
'{% macro page_w_children(pg) %}\n'
' <li class="dactyl-toc-entry"><a href="{{ pg.html }}">{{ '
'pg.name }}</a></li>\n'
' {% if pg.children %}\n'
' <ul>\n'
' {% for child in pg.children %}\n'
' {{ page_w_children(child) }}\n'
' {% endfor %}\n'
' </ul>\n'
' {% endif %}\n'
'{% endmacro %}\n'
'\n'
'{% for page in pages %}\n'
' {% if page.parent is undefined %}\n'
' {{ page_w_children(page) }}\n'
' {% endif %}\n'
'{% endfor %}\n'
'</ul>\n'
'\n'
'Results:',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything'],
'template': 'template-hierarchy.html'},
{'blurb': 'This page demonstrates custom filters in Dactyl. In "Metal Gear '
'Solid 2", the la-li-lu-le-lo are an organization who brainwash '
'people to say "la-li-lu-le-lo" instead of "la-li-lu-le-lo" when '
'speaking aloud, even among their compatriots.',
'category': 'Extending',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers', 'patriots'],
'foo': 'fooooooo',
'headermap': {'Custom Filter¶': '#custom-filter'},
'hover_anchors': '¶',
'html': 'filter-examples-patriots.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33ad30>,
'md': 'extending/patriots.md',
'name': 'Custom Filter',
'parent': 'extending-index.html',
'plaintext': 'Custom Filter¶\n'
'This page demonstrates custom filters in Dactyl. In "Metal '
'Gear Solid 2", the la-li-lu-le-lo are an organization who '
'brainwash people to say "la-li-lu-le-lo" instead of '
'"la-li-lu-le-lo" when speaking aloud, even among their '
'compatriots.\n'
'This page should read normally in the markdown source, but in '
'the Dactyl output if the patriots filter is enabled, all '
"instances of the la-li-lu-le-lo' name is replaced with "
'la-li-lu-le-lo.\n'
'If a custom filter name is satisfied by multiple custom filter '
'directories, or by a custom filter and by a Dactyl built-in '
'filter, the first listed custom filter directory takes highest '
'preference, and the Dactyl built-in filters are lowest '
'preference. However, if importing a filter fails (for example, '
'due to a syntax error), a lower-precedence filter with the '
'same name may be loaded instead.',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'blurb': 'This page demonstrates custom filters in Dactyl. In "Metal Gear '
'Solid 2", the La-Li-Lu-Le-Lo are an organization who brainwash '
'people to say "la-li-lu-le-lo" instead of "La-Li-Lu-Le-Lo" when '
'speaking aloud, even among their comla-li-lu-le-lo.',
'category': 'Extending',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers', 'patriots2'],
'foo': 'fooooooo',
'headermap': {'Custom Filter¶': '#custom-filter'},
'hover_anchors': '¶',
'html': 'filter-examples-patriots2.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33adc0>,
'md': 'extending/patriots.md',
'name': 'Custom Filter 2',
'parent': 'extending-index.html',
'plaintext': 'Custom Filter¶\n'
'This page demonstrates custom filters in Dactyl. In "Metal '
'Gear Solid 2", the La-Li-Lu-Le-Lo are an organization who '
'brainwash people to say "la-li-lu-le-lo" instead of '
'"La-Li-Lu-Le-Lo" when speaking aloud, even among their '
'comla-li-lu-le-lo.\n'
'This page should read normally in the markdown source, but in '
'the Dactyl output if the la-li-lu-le-lo filter is enabled, all '
"instances of the La-Li-Lu-Le-Lo' name is replaced with "
'la-li-lu-le-lo.\n'
'If a custom filter name is satisfied by multiple custom filter '
'directories, or by a custom filter and by a Dactyl built-in '
'filter, the first listed custom filter directory takes highest '
'preference, and the Dactyl built-in filters are lowest '
'preference. However, if importing a filter fails (for example, '
'due to a syntax error), a lower-precedence filter with the '
'same name may be loaded instead.',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'__dactyl_provided_filename__': True,
'blurb': 'The include_code filter provides a function that can make a code '
'sample from a file, pulling in just specific lines if desired.',
'category': 'Extending',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers', 'include_code'],
'foo': 'fooooooo',
'headermap': {'Code Includer¶': '#code-includer'},
'hover_anchors': '¶',
'html': 'include_code.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33ae50>,
'md': 'extending/include_code.md',
'name': 'Code Includer',
'parent': 'extending-index.html',
'plaintext': 'Code Includer¶\n'
'The include_code filter provides a function that can make a '
'code sample from a file, pulling in just specific lines if '
'desired.\n'
'Call it like so:\n'
'{{ include_code("sample_include.json", lines="1,3,5-6", '
'mark_disjoint=True) }}\n'
'\n'
'Sample:\n'
'{"line one": "here",\n'
'...\n'
'"third line": 3,\n'
'...\n'
' "line 5": "FIVE",\n'
'"six": 6\n'
'\n'
'One range:\n'
'"second line": true,\n'
'"third line": 3,\n'
' "4th line": [1,2,3,4],\n'
'\n'
'The whole file:\n'
'{"line one": "here",\n'
'"second line": true,\n'
'"third line": 3,\n'
' "4th line": [1,2,3,4],\n'
' "line 5": "FIVE",\n'
'"six": 6\n'
'}\n'
'\n'
'Custom separator string for disjoint lines:\n'
'{"line one": "here",\n'
'"second line": true,\n'
'... (line omitted)...\n'
' "4th line": [1,2,3,4],\n'
' "line 5": "FIVE",\n'
'"six": 6\n'
'}\n',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything']},
{'category': 'Extending',
'children': [],
'demote_headers_pdf_only': True,
'filters': ['demote_headers'],
'foo': 'fooooooo',
'hover_anchors': '¶',
'html': 'debug.html',
'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33aee0>,
'md': 'extending/debug.md',
'name': 'Debug',
'no_highlighting': True,
'parent': 'extending-index.html',
'skip_cover': True,
'stylesheet': 'template_assets/dactyl.css',
'targets': ['everything'],
'template': 'template-minimal.html'}]
currentpage¶
{'md': 'extending/debug.md', 'html': 'debug.html', 'category': 'Extending', 'parent': 'extending-index.html', 'template': 'template-minimal.html', 'no_highlighting': True, 'targets': ['everything'], 'filters': ['demote_headers'], 'name': 'Debug', 'hover_anchors': '¶', 'skip_cover': True, 'demote_headers_pdf_only': True, 'stylesheet': 'template_assets/dactyl.css', 'foo': 'fooooooo', 'children': [], 'is_ancestor_of': <function DactylTarget.make_ancestor_lookup.<locals>.is_ancestor_of at 0x7f9d9d33aee0>}
categories¶
['Features', 'Tests', 'Filters', 'Extending']
config¶
<dactyl.config.DactylConfig object at 0x7f9d9d3f7610>
current_time¶
2022-01-26
mode¶
html