Add cross-reference labeling.

hide label text

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.

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.

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)

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