diff options
author | Sadaf Ebrahimi <sadafebrahimi@google.com> | 2022-11-07 17:06:45 +0000 |
---|---|---|
committer | Automerger Merge Worker <android-build-automerger-merge-worker@system.gserviceaccount.com> | 2022-11-07 17:06:45 +0000 |
commit | b8ef043a4bce3c0e0c3a83a5309c17d1962be972 (patch) | |
tree | 1a110fa9fa982e746b1969458c5b9d373c70a38c /docs/extensions/meta_data.md | |
parent | f9792ce11873633749589df798950d128385a987 (diff) | |
parent | 41abd7141734af7b464f24a52d0405e0a0ebe63c (diff) | |
download | markdown-b8ef043a4bce3c0e0c3a83a5309c17d1962be972.tar.gz |
Merge "Upgrade markdown to 3.4.1" am: 79292f57ff am: 15d05f2d07 am: 41abd71417HEADandroid-14.0.0_r45android-14.0.0_r44android-14.0.0_r43android-14.0.0_r42android-14.0.0_r41android-14.0.0_r40android-14.0.0_r39android-14.0.0_r38android-14.0.0_r27android-14.0.0_r26android-14.0.0_r25android-14.0.0_r24android-14.0.0_r23android-14.0.0_r22android-14.0.0_r21android-14.0.0_r20android-14.0.0_r19android-14.0.0_r18android-14.0.0_r17android-14.0.0_r16aml_rkp_341510000aml_rkp_341311000aml_rkp_341114000aml_rkp_341015010aml_rkp_341012000aml_hef_341717050aml_hef_341613000aml_hef_341512030aml_hef_341415040aml_hef_341311010aml_hef_341114030aml_cfg_341510000mastermainandroid14-qpr1-s2-releaseandroid14-qpr1-releaseandroid14-mainline-healthfitness-releaseandroid14-devandroid14-d2-s5-releaseandroid14-d2-s4-releaseandroid14-d2-s3-releaseandroid14-d2-s2-releaseandroid14-d2-s1-releaseandroid14-d2-release
Original change: https://android-review.googlesource.com/c/platform/external/markdown/+/2288233
Change-Id: Ieca29d1e12802f580116844c0b5f1770313569c0
Signed-off-by: Automerger Merge Worker <android-build-automerger-merge-worker@system.gserviceaccount.com>
Diffstat (limited to 'docs/extensions/meta_data.md')
-rw-r--r-- | docs/extensions/meta_data.md | 113 |
1 files changed, 113 insertions, 0 deletions
diff --git a/docs/extensions/meta_data.md b/docs/extensions/meta_data.md new file mode 100644 index 0000000..d5a4c87 --- /dev/null +++ b/docs/extensions/meta_data.md @@ -0,0 +1,113 @@ +title: Meta-Data Extension + +Meta-Data +========= + +Summary +------- + +The Meta-Data extension adds a syntax for defining meta-data about a document. +It is inspired by and follows the syntax of [MultiMarkdown][]. Currently, +this extension does not use the meta-data in any way, but simply provides it as +a `Meta` attribute of a Markdown instance for use by other extensions or +directly by your python code. + +This extension is included in the standard Markdown library. + +[MultiMarkdown]: https://fletcherpenney.net/multimarkdown/#metadata + +Syntax +------ + +Meta-data consists of a series of keywords and values defined at the beginning +of a markdown document like this: + +```md +Title: My Document +Summary: A brief description of my document. +Authors: Waylan Limberg + John Doe +Date: October 2, 2007 +blank-value: +base_url: http://example.com + +This is the first paragraph of the document. +``` + +The keywords are case-insensitive and may consist of letters, numbers, +underscores and dashes and must end with a colon. The values consist of +anything following the colon on the line and may even be blank. + +If a line is indented by 4 or more spaces, that line is assumed to be an +additional line of the value for the previous keyword. A keyword may have as +many lines as desired. + +The first blank line ends all meta-data for the document. Therefore, the first +line of a document must not be blank. + +Alternatively, You may use YAML style deliminators to mark the start and/or end +of your meta-data. When doing so, the first line of your document must be `---`. +The meta-data ends at the first blank line or the first line containing an end +deliminator (either `---` or `...`), whichever comes first. Even though YAML +deliminators are supported, meta-data is not parsed as YAML. + +All meta-data is stripped from the document prior to any further processing +by Markdown. + +Usage +----- + +See [Extensions](index.md) for general extension usage. Use `meta` as the name +of the extension. + +A trivial example: + +```python +markdown.markdown(some_text, extensions=['meta']) +``` + +Accessing the Meta-Data +----------------------- + +The meta-data is made available as a python Dict in the `Meta` attribute of an +instance of the Markdown class. For example, using the above document: + +```pycon +>>> md = markdown.Markdown(extensions = ['meta']) +>>> html = md.convert(text) +>>> # Meta-data has been stripped from output +>>> print html +<p>This is the first paragraph of the document.</p> + +>>> # View meta-data +>>> print md.Meta +{ +'title' : ['My Document'], +'summary' : ['A brief description of my document.'], +'authors' : ['Waylan Limberg', 'John Doe'], +'date' : ['October 2, 2007'], +'blank-value' : [''], +'base_url' : ['http://example.com'] +} +``` + +Note that the keys are all lowercase and the values consist of a list of +strings where each item is one line for that key. This way, one could preserve +line breaks if desired. Or the items could be joined where appropriate. No +assumptions are made regarding the data. It is simply passed as found to the +`Meta` attribute. + +Perhaps the meta-data could be passed into a template system, or used by +various Markdown extensions. The possibilities are left to the imagination of +the developer. + +Compatible Extensions +--------------------- + +The following extensions are currently known to work with the Meta-Data +extension. The keywords they are known to support are also listed. + +* [WikiLinks](wikilinks.md) + * `wiki_base_url` + * `wiki_end_url` + * `wiki_html_class` |