diff --git a/README.md b/README.md index a44600d..7486e89 100644 --- a/README.md +++ b/README.md @@ -111,6 +111,7 @@ AutoStructify comes with the following options. See [http://recommonmark.readthe * __enable_math__: enable the Math Formula feature. * __enable_inline_math__: enable the Inline Math feature. * __enable_eval_rst__: enable the evaluate embedded reStructuredText feature. +* __enable_label__: enable the cross-referencing label feature. * __url_resolver__: a function that maps a existing relative position in the document to a http link * __known_url_schemes__: a list of url schemes to treat as URLs, schemes not in this list will be assumed to be Sphinx cross-references. Defaults to `None`, which means treat all URL schemes as URLs. diff --git a/docs/auto_structify.md b/docs/auto_structify.md index 409f176..cdb5721 100644 --- a/docs/auto_structify.md +++ b/docs/auto_structify.md @@ -34,6 +34,7 @@ All the features are by default enabled * __enable_math__: whether enable [Math Formula](#math-formula) * __enable_inline_math__: whether enable [Inline Math](#inline-math) * __enable_eval_rst__: whether [Embed reStructuredText](#embed-restructuredtext) is enabled. +* __enable_label_rst__: whether [Cross-reference Labels](#embed-reference-label) is enabled. * __url_resolver__: a function that maps a existing relative position in the document to a http link Auto Toc Tree @@ -150,6 +151,21 @@ will be rendered as E = m c^2 ``` +### Embed Reference Labels +You can embed reference labels via a `label` code block. The first line of that block is parsed as that label. + +Example +```` +```label +a-label +``` +```` + +Is equivalent to +```rst +.. _a-label: +``` + ### Embed reStructuredText Recommonmark also allows embedding reStructuredText syntax in the codeblocks. diff --git a/docs/conf.py b/docs/conf.py index a67cc99..0f6a96b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -299,5 +299,6 @@ def setup(app): 'enable_inline_math': False, 'enable_eval_rst': True, 'enable_auto_doc_ref': True, + 'enable_label': True }, True) app.add_transform(AutoStructify) diff --git a/recommonmark/transform.py b/recommonmark/transform.py index 649035a..672a239 100644 --- a/recommonmark/transform.py +++ b/recommonmark/transform.py @@ -50,6 +50,7 @@ class AutoStructify(transforms.Transform): 'commonmark_suffixes': ['.md'], 'url_resolver': lambda x: x, 'known_url_schemes': None, + 'enable_label': True, } def parse_ref(self, ref): @@ -242,6 +243,14 @@ class AutoStructify(transforms.Transform): if self.config['enable_math']: return self.state_machine.run_directive( 'math', content=content) + elif language == 'label': + if self.config['enable_label']: + node = nodes.section() + self.state_machine.state.nested_parse( + StringList(['.. _' + content[0] + ':', ''], + source=''), + 0, node=node, match_titles=True) + return node.children[:] elif language == 'eval_rst': if self.config['enable_eval_rst']: # allow embed non section level rst