Do not HTML-escape and use Markdown inline code for defaults (#161)
Reverts #133 so that HTML escaping is not applied to Markdown. Instead, Markdown content such as docstrings can use HTML formatting and escape angle brackets with backslashes, HTML entities or inline code segments. Default values are embedded in inline code segments instead of `<code>` tags, which does not require escaping.
As a result, docstrings behave just like regular Markdown contexts while default values are rendered without smart quotes and can contain both `<` and `` ` `` without causing escaping issues.
Also includes tests based on #138.
Fixes #137
Closes #138
Fixes #142
Closes #143
Requires https://github.com/bazelbuild/bazel/pull/18867
Co-authored-by: Adam Azarchs <adam.azarchs@10xgenomics.com>
diff --git a/docs/stardoc_rule.md b/docs/stardoc_rule.md
index 2532abe..8e45059 100644
--- a/docs/stardoc_rule.md
+++ b/docs/stardoc_rule.md
@@ -21,17 +21,17 @@
| <a id="stardoc-name"></a>name | The name of the stardoc target. | none |
| <a id="stardoc-input"></a>input | The starlark file to generate documentation for (mandatory). | none |
| <a id="stardoc-out"></a>out | The file to which documentation will be output (mandatory). | none |
-| <a id="stardoc-deps"></a>deps | A list of bzl_library dependencies which the input depends on. | <code>[]</code> |
-| <a id="stardoc-format"></a>format | The format of the output file. Valid values: 'markdown' or 'proto'. | <code>"markdown"</code> |
-| <a id="stardoc-symbol_names"></a>symbol_names | A list of symbol names to generate documentation for. These should correspond to the names of rule definitions in the input file. If this list is empty, then documentation for all exported rule definitions will be generated. | <code>[]</code> |
-| <a id="stardoc-semantic_flags"></a>semantic_flags | A list of canonical flags to affect Starlark semantics for the Starlark interpreter during documentation generation. This should only be used to maintain compatibility with non-default semantic flags required to use the given Starlark symbols.<br><br>For example, if <code>//foo:bar.bzl</code> does not build except when a user would specify <code>--incompatible_foo_semantic=false</code>, then this attribute should contain "--incompatible_foo_semantic=false". | <code>[]</code> |
-| <a id="stardoc-stardoc"></a>stardoc | The location of the stardoc tool. | <code>Label("//stardoc:prebuilt_stardoc_binary")</code> |
-| <a id="stardoc-renderer"></a>renderer | The location of the renderer tool. | <code>Label("//stardoc:renderer")</code> |
-| <a id="stardoc-aspect_template"></a>aspect_template | The input file template for generating documentation of aspects | <code>Label("//stardoc:templates/markdown_tables/aspect.vm")</code> |
-| <a id="stardoc-func_template"></a>func_template | The input file template for generating documentation of functions. | <code>Label("//stardoc:templates/markdown_tables/func.vm")</code> |
-| <a id="stardoc-header_template"></a>header_template | The input file template for the header of the output documentation. | <code>Label("//stardoc:templates/markdown_tables/header.vm")</code> |
-| <a id="stardoc-provider_template"></a>provider_template | The input file template for generating documentation of providers. | <code>Label("//stardoc:templates/markdown_tables/provider.vm")</code> |
-| <a id="stardoc-rule_template"></a>rule_template | The input file template for generating documentation of rules. | <code>Label("//stardoc:templates/markdown_tables/rule.vm")</code> |
+| <a id="stardoc-deps"></a>deps | A list of bzl_library dependencies which the input depends on. | `[]` |
+| <a id="stardoc-format"></a>format | The format of the output file. Valid values: 'markdown' or 'proto'. | `"markdown"` |
+| <a id="stardoc-symbol_names"></a>symbol_names | A list of symbol names to generate documentation for. These should correspond to the names of rule definitions in the input file. If this list is empty, then documentation for all exported rule definitions will be generated. | `[]` |
+| <a id="stardoc-semantic_flags"></a>semantic_flags | A list of canonical flags to affect Starlark semantics for the Starlark interpreter during documentation generation. This should only be used to maintain compatibility with non-default semantic flags required to use the given Starlark symbols.<br><br>For example, if <code>//foo:bar.bzl</code> does not build except when a user would specify <code>--incompatible_foo_semantic=false</code>, then this attribute should contain "--incompatible_foo_semantic=false". | `[]` |
+| <a id="stardoc-stardoc"></a>stardoc | The location of the stardoc tool. | `Label("//stardoc:prebuilt_stardoc_binary")` |
+| <a id="stardoc-renderer"></a>renderer | The location of the renderer tool. | `Label("//stardoc:renderer")` |
+| <a id="stardoc-aspect_template"></a>aspect_template | The input file template for generating documentation of aspects | `Label("//stardoc:templates/markdown_tables/aspect.vm")` |
+| <a id="stardoc-func_template"></a>func_template | The input file template for generating documentation of functions. | `Label("//stardoc:templates/markdown_tables/func.vm")` |
+| <a id="stardoc-header_template"></a>header_template | The input file template for the header of the output documentation. | `Label("//stardoc:templates/markdown_tables/header.vm")` |
+| <a id="stardoc-provider_template"></a>provider_template | The input file template for generating documentation of providers. | `Label("//stardoc:templates/markdown_tables/provider.vm")` |
+| <a id="stardoc-rule_template"></a>rule_template | The input file template for generating documentation of rules. | `Label("//stardoc:templates/markdown_tables/rule.vm")` |
| <a id="stardoc-kwargs"></a>kwargs | Further arguments to pass to stardoc. | none |
diff --git a/stardoc/templates/markdown_tables/aspect.vm b/stardoc/templates/markdown_tables/aspect.vm
index aa9f13b..36aa47a 100644
--- a/stardoc/templates/markdown_tables/aspect.vm
+++ b/stardoc/templates/markdown_tables/aspect.vm
@@ -6,7 +6,7 @@
${util.aspectSummary($aspectName, $aspectInfo)}
</pre>
-${util.htmlEscape($aspectInfo.getDocString())}
+$aspectInfo.getDocString()
**ASPECT ATTRIBUTES**
@@ -27,6 +27,6 @@
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
#foreach ($attribute in $aspectInfo.getAttributeList())
-| <a id="${aspectName}-${attribute.name}"></a>$attribute.name | #if(!$attribute.docString.isEmpty()) ${util.markdownCellFormat($attribute.docString)} #else - #end | ${util.attributeTypeString($attribute)} | ${util.mandatoryString($attribute)} | #if(!$attribute.defaultValue.isEmpty()) <code>${util.htmlEscape($attribute.defaultValue)}</code> #end |
+| <a id="${aspectName}-${attribute.name}"></a>$attribute.name | #if(!$attribute.docString.isEmpty()) ${util.markdownCellFormat($attribute.docString)} #else - #end | ${util.attributeTypeString($attribute)} | ${util.mandatoryString($attribute)} | #if(!$attribute.defaultValue.isEmpty()) ${util.markdownCodeSpan($attribute.defaultValue)} #end |
#end
#end
diff --git a/stardoc/templates/markdown_tables/func.vm b/stardoc/templates/markdown_tables/func.vm
index 5275d08..e53b81a 100644
--- a/stardoc/templates/markdown_tables/func.vm
+++ b/stardoc/templates/markdown_tables/func.vm
@@ -6,7 +6,7 @@
${util.funcSummary($funcInfo)}
</pre>
-${util.htmlEscape($funcInfo.docString)}
+${funcInfo.docString}
#if (!$funcInfo.getParameterList().isEmpty())
**PARAMETERS**
@@ -15,18 +15,18 @@
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
#foreach ($param in $funcInfo.getParameterList())
-| <a id="${funcInfo.functionName}-${param.name}"></a>$param.name | #if(!$param.docString.isEmpty()) ${util.markdownCellFormat($param.docString)} #else <p align="center"> - </p> #end | #if(!$param.getDefaultValue().isEmpty()) <code>${util.htmlEscape($param.getDefaultValue())}</code> #else none #end|
+| <a id="${funcInfo.functionName}-${param.name}"></a>$param.name | #if(!$param.docString.isEmpty()) ${util.markdownCellFormat($param.docString)} #else <p align="center"> - </p> #end | #if(!$param.getDefaultValue().isEmpty()) ${util.markdownCodeSpan($param.defaultValue)} #else none #end|
#end
#end
#if (!$funcInfo.getReturn().docString.isEmpty())
**RETURNS**
-${util.htmlEscape($funcInfo.getReturn().docString)}
+${funcInfo.getReturn().docString}
#end
#if (!$funcInfo.getDeprecated().docString.isEmpty())
**DEPRECATED**
-${util.htmlEscape($funcInfo.getDeprecated().docString)}
+${funcInfo.getDeprecated().docString}
#end
diff --git a/stardoc/templates/markdown_tables/header.vm b/stardoc/templates/markdown_tables/header.vm
index 2b47292..5556ad6 100644
--- a/stardoc/templates/markdown_tables/header.vm
+++ b/stardoc/templates/markdown_tables/header.vm
@@ -1,3 +1,3 @@
<!-- Generated with Stardoc: http://skydoc.bazel.build -->
-${util.htmlEscape($moduleDocstring)}
+${moduleDocstring}
diff --git a/stardoc/templates/markdown_tables/provider.vm b/stardoc/templates/markdown_tables/provider.vm
index 7ab4c60..0a866db 100644
--- a/stardoc/templates/markdown_tables/provider.vm
+++ b/stardoc/templates/markdown_tables/provider.vm
@@ -6,7 +6,7 @@
${util.providerSummary($providerName, $providerInfo)}
</pre>
-${util.htmlEscape($providerInfo.docString)}
+${providerInfo.docString}
**FIELDS**
diff --git a/stardoc/templates/markdown_tables/rule.vm b/stardoc/templates/markdown_tables/rule.vm
index 06d9a1f..0b73239 100644
--- a/stardoc/templates/markdown_tables/rule.vm
+++ b/stardoc/templates/markdown_tables/rule.vm
@@ -6,7 +6,7 @@
${util.ruleSummary($ruleName, $ruleInfo)}
</pre>
-${util.htmlEscape($ruleInfo.docString)}
+${ruleInfo.docString}
**ATTRIBUTES**
@@ -15,6 +15,6 @@
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
#foreach ($attribute in $ruleInfo.getAttributeList())
-| <a id="${ruleName}-${attribute.name}"></a>$attribute.name | #if(!$attribute.docString.isEmpty()) ${util.markdownCellFormat($attribute.docString)} #else - #end | ${util.attributeTypeString($attribute)} | ${util.mandatoryString($attribute)} | #if(!$attribute.defaultValue.isEmpty())<code>${util.htmlEscape($attribute.defaultValue)}</code>#end |
+| <a id="${ruleName}-${attribute.name}"></a>$attribute.name | #if(!$attribute.docString.isEmpty()) ${util.markdownCellFormat($attribute.docString)} #else - #end | ${util.attributeTypeString($attribute)} | ${util.mandatoryString($attribute)} | #if(!$attribute.defaultValue.isEmpty()) ${util.markdownCodeSpan($attribute.defaultValue)} #end |
#end
#end
diff --git a/test/testdata/android_basic_test/golden.md b/test/testdata/android_basic_test/golden.md
index 0962201..b22186d 100755
--- a/test/testdata/android_basic_test/golden.md
+++ b/test/testdata/android_basic_test/golden.md
@@ -19,7 +19,7 @@
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="android_related_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
| <a id="android_related_rule-first"></a>first | - | <a href="https://bazel.build/concepts/labels">Label</a> | required | |
-| <a id="android_related_rule-fourth"></a>fourth | - | Boolean | optional | <code>False</code> |
+| <a id="android_related_rule-fourth"></a>fourth | - | Boolean | optional | `False` |
| <a id="android_related_rule-second"></a>second | - | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required | |
| <a id="android_related_rule-third"></a>third | - | <a href="https://bazel.build/concepts/labels">Label</a> | required | |
diff --git a/test/testdata/angle_bracket_test/golden.md b/test/testdata/angle_bracket_test/golden.md
index 1c31dd2..a9ccc14 100755
--- a/test/testdata/angle_bracket_test/golden.md
+++ b/test/testdata/angle_bracket_test/golden.md
@@ -1,19 +1,27 @@
<!-- Generated with Stardoc: http://skydoc.bazel.build -->
-Input file to test <angle bracket bugs>
+Input file to test angle bracket bug (https://github.com/bazelbuild/skydoc/issues/186)
-See https://github.com/bazelbuild/skydoc/issues/186
-and https://github.com/bazelbuild/stardoc/issues/132
+See https://github.com/bazelbuild/skydoc/issues/186,
+https://github.com/bazelbuild/stardoc/issues/132,
+and https://github.com/bazelbuild/stardoc/issues/137.
+
+<b>HTML formatting</b> can be used in docstrings, just as in regular Markdown.
+Literal angle brackets can be obtained by escaping them with a backslash, where
+the backslash itself must be escaped for use in a Starlark docstring
+(`\\<` becomes \<), or by using HTML entities (`<` becomes <).
+Angle brackets are also preserved in inline code blocks (`#include <vector>`).
+
<a id="my_anglebrac"></a>
## my_anglebrac
<pre>
-my_anglebrac(<a href="#my_anglebrac-name">name</a>, <a href="#my_anglebrac-useless">useless</a>)
+my_anglebrac(<a href="#my_anglebrac-name">name</a>, <a href="#my_anglebrac-also_useless">also_useless</a>, <a href="#my_anglebrac-useless">useless</a>)
</pre>
-Rule with <brackets>
+Rule with \<brackets>
**ATTRIBUTES**
@@ -21,7 +29,8 @@
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="my_anglebrac-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
-| <a id="my_anglebrac-useless"></a>useless | Args with some tags: <tag1>, <tag2> | String | optional | <code>"Find <brackets>"</code> |
+| <a id="my_anglebrac-also_useless"></a>also_useless | Args with some formatted tags: <code><tag></code> | String | optional | `"1<<5"` |
+| <a id="my_anglebrac-useless"></a>useless | Args with some tags: <tag1>, <tag2> | String | optional | `"Find \<brackets>"` |
<a id="bracketuse"></a>
@@ -32,7 +41,7 @@
bracketuse(<a href="#bracketuse-foo">foo</a>, <a href="#bracketuse-bar">bar</a>, <a href="#bracketuse-baz">baz</a>)
</pre>
-Information with <brackets>
+Information with \<brackets>
**FIELDS**
@@ -49,12 +58,19 @@
## bracket_function
<pre>
-bracket_function(<a href="#bracket_function-param">param</a>)
+bracket_function(<a href="#bracket_function-param">param</a>, <a href="#bracket_function-md_string">md_string</a>)
</pre>
-Dummy docstring with <brackets>.
+Dummy docstring with \<brackets>.
-This rule runs checks on <angle brackets>.
+This rule runs checks on `<angle brackets>`.
+
+Sometimes, we have such things on their own, but they may
+also appear in code blocks, like
+
+```starlark
+foo = "<thing>"
+```
**PARAMETERS**
@@ -62,15 +78,16 @@
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
-| <a id="bracket_function-param"></a>param | an arg with **formatted** docstring, <default> by default. | <code>"<default>"</code> |
+| <a id="bracket_function-param"></a>param | an arg with **formatted** docstring, <code><default></code> by default. | `"<default>"` |
+| <a id="bracket_function-md_string"></a>md_string | A markdown string. | ``"foo `1<<10` bar"`` |
**RETURNS**
-some <angled> brackets
+some \<angled> brackets
**DEPRECATED**
-deprecated for <reasons>
+deprecated for \<reasons> as well as `<reasons>`.
<a id="bracket_aspect"></a>
@@ -81,7 +98,14 @@
bracket_aspect(<a href="#bracket_aspect-name">name</a>, <a href="#bracket_aspect-brackets">brackets</a>)
</pre>
-Aspect with <brackets>
+Aspect.
+
+Sometimes, we want a code block like
+```starlark
+foo = "<brackets>"
+```
+which includes angle brackets.
+
**ASPECT ATTRIBUTES**
@@ -96,7 +120,7 @@
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
-| <a id="bracket_aspect-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
-| <a id="bracket_aspect-brackets"></a>brackets | Attribute with <brackets> | String | optional | <code>"<default>"</code> |
+| <a id="bracket_aspect-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
+| <a id="bracket_aspect-brackets"></a>brackets | Attribute with \<brackets> | String | optional | `"<default>"` |
diff --git a/test/testdata/angle_bracket_test/input.bzl b/test/testdata/angle_bracket_test/input.bzl
index 4df0e1f..6ef8c40 100644
--- a/test/testdata/angle_bracket_test/input.bzl
+++ b/test/testdata/angle_bracket_test/input.bzl
@@ -1,27 +1,43 @@
-"""Input file to test <angle bracket bugs>
+"""Input file to test angle bracket bug (https://github.com/bazelbuild/skydoc/issues/186)
-See https://github.com/bazelbuild/skydoc/issues/186
-and https://github.com/bazelbuild/stardoc/issues/132"""
+See https://github.com/bazelbuild/skydoc/issues/186,
+https://github.com/bazelbuild/stardoc/issues/132,
+and https://github.com/bazelbuild/stardoc/issues/137.
-def bracket_function(param = "<default>"):
- """Dummy docstring with <brackets>.
+<b>HTML formatting</b> can be used in docstrings, just as in regular Markdown.
+Literal angle brackets can be obtained by escaping them with a backslash, where
+the backslash itself must be escaped for use in a Starlark docstring
+(`\\\\<` becomes \\<), or by using HTML entities (`<` becomes <).
+Angle brackets are also preserved in inline code blocks (`#include <vector>`).
+"""
- This rule runs checks on <angle brackets>.
+def bracket_function(param = "<default>", md_string = "foo `1<<10` bar"):
+ """Dummy docstring with \\<brackets>.
+
+ This rule runs checks on `<angle brackets>`.
+
+ Sometimes, we have such things on their own, but they may
+ also appear in code blocks, like
+
+ ```starlark
+ foo = "<thing>"
+ ```
Args:
- param: an arg with **formatted** docstring, <default> by default.
+ param: an arg with **formatted** docstring, `<default>` by default.
+ md_string: A markdown string.
Returns:
- some <angled> brackets
+ some \\<angled> brackets
Deprecated:
- deprecated for <reasons>
+ deprecated for \\<reasons> as well as `<reasons>`.
"""
- return param
+ return param or md_string
# buildifier: disable=unsorted-dict-items
bracketuse = provider(
- doc = "Information with <brackets>",
+ doc = "Information with \\<brackets>",
fields = {
"foo": "A string representing <foo>",
"bar": "A string representing bar",
@@ -35,11 +51,15 @@
my_anglebrac = rule(
implementation = _rule_impl,
- doc = "Rule with <brackets>",
+ doc = "Rule with \\<brackets>",
attrs = {
"useless": attr.string(
doc = "Args with some tags: <tag1>, <tag2>",
- default = "Find <brackets>",
+ default = "Find \\<brackets>",
+ ),
+ "also_useless": attr.string(
+ doc = "Args with some formatted tags: `<tag>`",
+ default = "1<<5",
),
},
)
@@ -50,11 +70,18 @@
bracket_aspect = aspect(
implementation = _bracket_aspect_impl,
- doc = "Aspect with <brackets>",
+ doc = """Aspect.
+
+Sometimes, we want a code block like
+```starlark
+foo = "<brackets>"
+```
+which includes angle brackets.
+""",
attr_aspects = ["deps"],
attrs = {
"brackets": attr.string(
- doc = "Attribute with <brackets>",
+ doc = "Attribute with \\<brackets>",
default = "<default>",
),
},
diff --git a/test/testdata/apple_basic_test/golden.md b/test/testdata/apple_basic_test/golden.md
index 5a9eb6e..b9e7a5b 100755
--- a/test/testdata/apple_basic_test/golden.md
+++ b/test/testdata/apple_basic_test/golden.md
@@ -19,7 +19,7 @@
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="apple_related_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
| <a id="apple_related_rule-first"></a>first | - | <a href="https://bazel.build/concepts/labels">Label</a> | required | |
-| <a id="apple_related_rule-fourth"></a>fourth | - | Boolean | optional | <code>False</code> |
+| <a id="apple_related_rule-fourth"></a>fourth | - | Boolean | optional | `False` |
| <a id="apple_related_rule-second"></a>second | - | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required | |
| <a id="apple_related_rule-third"></a>third | - | <a href="https://bazel.build/concepts/labels">Label</a> | required | |
diff --git a/test/testdata/aspect_test/golden.md b/test/testdata/aspect_test/golden.md
index b422fc7..b61e57a 100755
--- a/test/testdata/aspect_test/golden.md
+++ b/test/testdata/aspect_test/golden.md
@@ -44,9 +44,9 @@
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
-| <a id="my_aspect-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
-| <a id="my_aspect-first"></a>first | - | Boolean | required | |
-| <a id="my_aspect-second"></a>second | - | String | required | |
+| <a id="my_aspect-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
+| <a id="my_aspect-first"></a>first | - | Boolean | required | |
+| <a id="my_aspect-second"></a>second | - | String | required | |
<a id="other_aspect"></a>
@@ -72,7 +72,7 @@
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
-| <a id="other_aspect-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
-| <a id="other_aspect-third"></a>third | - | Integer | required | |
+| <a id="other_aspect-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
+| <a id="other_aspect-third"></a>third | - | Integer | required | |
diff --git a/test/testdata/attribute_defaults_test/golden.md b/test/testdata/attribute_defaults_test/golden.md
index ae62b4c..4eaf4b9 100755
--- a/test/testdata/attribute_defaults_test/golden.md
+++ b/test/testdata/attribute_defaults_test/golden.md
@@ -18,16 +18,16 @@
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="my_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
-| <a id="my_rule-a"></a>a | Some bool | Boolean | optional | <code>False</code> |
-| <a id="my_rule-b"></a>b | Some int | Integer | optional | <code>2</code> |
-| <a id="my_rule-c"></a>c | Some int_list | List of integers | optional | <code>[0, 1]</code> |
-| <a id="my_rule-d"></a>d | Some label | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>//foo:bar</code> |
-| <a id="my_rule-e"></a>e | Some label_keyed_string_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: Label -> String</a> | optional | <code>{"//foo:bar": "hello", "//bar:baz": "goodbye"}</code> |
-| <a id="my_rule-f"></a>f | Some label_list | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>["//foo:bar", "//bar:baz"]</code> |
-| <a id="my_rule-g"></a>g | Some string | String | optional | <code>""</code> |
-| <a id="my_rule-h"></a>h | Some string_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | <code>{"animal": "bunny", "color": "orange"}</code> |
-| <a id="my_rule-i"></a>i | Some string_list | List of strings | optional | <code>["cat", "dog"]</code> |
-| <a id="my_rule-j"></a>j | Some string_list_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> List of strings</a> | optional | <code>{"animal": ["cat", "bunny"], "color": ["blue", "orange"]}</code> |
+| <a id="my_rule-a"></a>a | Some bool | Boolean | optional | `False` |
+| <a id="my_rule-b"></a>b | Some int | Integer | optional | `2` |
+| <a id="my_rule-c"></a>c | Some int_list | List of integers | optional | `[0, 1]` |
+| <a id="my_rule-d"></a>d | Some label | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `//foo:bar` |
+| <a id="my_rule-e"></a>e | Some label_keyed_string_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: Label -> String</a> | optional | `{"//foo:bar": "hello", "//bar:baz": "goodbye"}` |
+| <a id="my_rule-f"></a>f | Some label_list | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `["//foo:bar", "//bar:baz"]` |
+| <a id="my_rule-g"></a>g | Some string | String | optional | `""` |
+| <a id="my_rule-h"></a>h | Some string_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | `{"animal": "bunny", "color": "orange"}` |
+| <a id="my_rule-i"></a>i | Some string_list | List of strings | optional | `["cat", "dog"]` |
+| <a id="my_rule-j"></a>j | Some string_list_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> List of strings</a> | optional | `{"animal": ["cat", "bunny"], "color": ["blue", "orange"]}` |
| <a id="my_rule-k"></a>k | Some bool | Boolean | required | |
| <a id="my_rule-l"></a>l | Some int | Integer | required | |
| <a id="my_rule-m"></a>m | Some int_list | List of integers | required | |
@@ -38,9 +38,9 @@
| <a id="my_rule-r"></a>r | Some string_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required | |
| <a id="my_rule-s"></a>s | Some string_list | List of strings | required | |
| <a id="my_rule-t"></a>t | Some string_list_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> List of strings</a> | required | |
-| <a id="my_rule-u"></a>u | - | String | optional | <code>""</code> |
-| <a id="my_rule-v"></a>v | - | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>None</code> |
-| <a id="my_rule-w"></a>w | - | Integer | optional | <code>0</code> |
+| <a id="my_rule-u"></a>u | - | String | optional | `""` |
+| <a id="my_rule-v"></a>v | - | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` |
+| <a id="my_rule-w"></a>w | - | Integer | optional | `0` |
<a id="my_aspect"></a>
@@ -67,8 +67,8 @@
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
-| <a id="my_aspect-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
-| <a id="my_aspect-y"></a>y | some string | String | optional | <code>"why"</code> |
-| <a id="my_aspect-z"></a>z | - | String | required | |
+| <a id="my_aspect-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
+| <a id="my_aspect-y"></a>y | some string | String | optional | `"why"` |
+| <a id="my_aspect-z"></a>z | - | String | required | |
diff --git a/test/testdata/attribute_types_test/golden.md b/test/testdata/attribute_types_test/golden.md
index 9a988c1..4df4916 100755
--- a/test/testdata/attribute_types_test/golden.md
+++ b/test/testdata/attribute_types_test/golden.md
@@ -29,6 +29,6 @@
| <a id="my_rule-i"></a>i | Some string | String | required | |
| <a id="my_rule-j"></a>j | Some string_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required | |
| <a id="my_rule-k"></a>k | Some string_list | List of strings | required | |
-| <a id="my_rule-l"></a>l | Some string_list_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> List of strings</a> | optional | <code>{}</code> |
+| <a id="my_rule-l"></a>l | Some string_list_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> List of strings</a> | optional | `{}` |
diff --git a/test/testdata/cc_api_test/golden.md b/test/testdata/cc_api_test/golden.md
index 10ca7f8..183402e 100755
--- a/test/testdata/cc_api_test/golden.md
+++ b/test/testdata/cc_api_test/golden.md
@@ -19,7 +19,7 @@
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="cpp_related_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
| <a id="cpp_related_rule-first"></a>first | - | <a href="https://bazel.build/concepts/labels">Label</a> | required | |
-| <a id="cpp_related_rule-fourth"></a>fourth | - | Boolean | optional | <code>False</code> |
+| <a id="cpp_related_rule-fourth"></a>fourth | - | Boolean | optional | `False` |
| <a id="cpp_related_rule-second"></a>second | - | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required | |
| <a id="cpp_related_rule-third"></a>third | - | <a href="https://bazel.build/concepts/labels">Label</a> | required | |
diff --git a/test/testdata/cpp_basic_test/golden.md b/test/testdata/cpp_basic_test/golden.md
index 7061e26..abce00a 100755
--- a/test/testdata/cpp_basic_test/golden.md
+++ b/test/testdata/cpp_basic_test/golden.md
@@ -19,7 +19,7 @@
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="cpp_related_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
| <a id="cpp_related_rule-first"></a>first | - | <a href="https://bazel.build/concepts/labels">Label</a> | required | |
-| <a id="cpp_related_rule-fourth"></a>fourth | - | Boolean | optional | <code>False</code> |
+| <a id="cpp_related_rule-fourth"></a>fourth | - | Boolean | optional | `False` |
| <a id="cpp_related_rule-second"></a>second | - | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required | |
| <a id="cpp_related_rule-third"></a>third | - | <a href="https://bazel.build/concepts/labels">Label</a> | required | |
diff --git a/test/testdata/function_basic_test/golden.md b/test/testdata/function_basic_test/golden.md
index 3f72514..d3db17d 100755
--- a/test/testdata/function_basic_test/golden.md
+++ b/test/testdata/function_basic_test/golden.md
@@ -24,12 +24,12 @@
| :------------- | :------------- | :------------- |
| <a id="check_sources-name"></a>name | A unique name for this rule. | none |
| <a id="check_sources-required_param"></a>required_param | Use your imagination. | none |
-| <a id="check_sources-bool_param"></a>bool_param | <p align="center"> - </p> | <code>True</code> |
-| <a id="check_sources-srcs"></a>srcs | Source files to run the checks against. | <code>[]</code> |
-| <a id="check_sources-string_param"></a>string_param | <p align="center"> - </p> | <code>""</code> |
-| <a id="check_sources-int_param"></a>int_param | Your favorite number. | <code>2</code> |
-| <a id="check_sources-dict_param"></a>dict_param | <p align="center"> - </p> | <code>{}</code> |
-| <a id="check_sources-struct_param"></a>struct_param | <p align="center"> - </p> | <code>struct(foo = "bar")</code> |
+| <a id="check_sources-bool_param"></a>bool_param | <p align="center"> - </p> | `True` |
+| <a id="check_sources-srcs"></a>srcs | Source files to run the checks against. | `[]` |
+| <a id="check_sources-string_param"></a>string_param | <p align="center"> - </p> | `""` |
+| <a id="check_sources-int_param"></a>int_param | Your favorite number. | `2` |
+| <a id="check_sources-dict_param"></a>dict_param | <p align="center"> - </p> | `{}` |
+| <a id="check_sources-struct_param"></a>struct_param | <p align="center"> - </p> | `struct(foo = "bar")` |
<a id="deprecated_do_not_use"></a>
diff --git a/test/testdata/function_wrap_multiple_lines_test/golden.md b/test/testdata/function_wrap_multiple_lines_test/golden.md
index 2f1a8a4..817f02b 100644
--- a/test/testdata/function_wrap_multiple_lines_test/golden.md
+++ b/test/testdata/function_wrap_multiple_lines_test/golden.md
@@ -21,36 +21,36 @@
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="antlr-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
-| <a id="antlr-deps"></a>deps | The dependencies to use. Defaults to the most recent ANTLR 3 release, but if you need to use a different version, you can specify the dependencies here. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[Label("@antlr3_runtimes//:tool")]</code> |
+| <a id="antlr-deps"></a>deps | The dependencies to use. Defaults to the most recent ANTLR 3 release, but if you need to use a different version, you can specify the dependencies here. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[Label("@antlr3_runtimes//:tool")]` |
| <a id="antlr-srcs"></a>srcs | The grammar files to process. | <a href="https://bazel.build/concepts/labels">List of labels</a> | required | |
-| <a id="antlr-Xconversiontimeout"></a>Xconversiontimeout | Set NFA conversion timeout for each decision. | Integer | optional | <code>0</code> |
-| <a id="antlr-Xdbgconversion"></a>Xdbgconversion | Dump lots of info during NFA conversion. | Boolean | optional | <code>False</code> |
-| <a id="antlr-Xdbgst"></a>Xdbgst | Put tags at start/stop of all templates in output. | Boolean | optional | <code>False</code> |
-| <a id="antlr-Xdfa"></a>Xdfa | Print DFA as text. | Boolean | optional | <code>False</code> |
-| <a id="antlr-Xdfaverbose"></a>Xdfaverbose | Generate DFA states in DOT with NFA configs. | Boolean | optional | <code>False</code> |
-| <a id="antlr-Xgrtree"></a>Xgrtree | Print the grammar AST. | Boolean | optional | <code>False</code> |
-| <a id="antlr-Xm"></a>Xm | Max number of rule invocations during conversion. | Integer | optional | <code>0</code> |
-| <a id="antlr-Xmaxdfaedges"></a>Xmaxdfaedges | Max "comfortable" number of edges for single DFA state. | Integer | optional | <code>0</code> |
-| <a id="antlr-Xmaxinlinedfastates"></a>Xmaxinlinedfastates | Max DFA states before table used rather than inlining. | Integer | optional | <code>0</code> |
-| <a id="antlr-Xminswitchalts"></a>Xminswitchalts | Don't generate switch() statements for dfas smaller than given number. | Integer | optional | <code>0</code> |
-| <a id="antlr-Xmultithreaded"></a>Xmultithreaded | Run the analysis in 2 threads. | Boolean | optional | <code>False</code> |
-| <a id="antlr-Xnfastates"></a>Xnfastates | For nondeterminisms, list NFA states for each path. | Boolean | optional | <code>False</code> |
-| <a id="antlr-Xnocollapse"></a>Xnocollapse | Collapse incident edges into DFA states. | Boolean | optional | <code>False</code> |
-| <a id="antlr-Xnomergestopstates"></a>Xnomergestopstates | Max DFA states before table used rather than inlining. | Boolean | optional | <code>False</code> |
-| <a id="antlr-Xnoprune"></a>Xnoprune | Do not test EBNF block exit branches. | Boolean | optional | <code>False</code> |
-| <a id="antlr-XsaveLexer"></a>XsaveLexer | For nondeterminisms, list NFA states for each path. | Boolean | optional | <code>False</code> |
-| <a id="antlr-Xwatchconversion"></a>Xwatchconversion | Don't delete temporary lexers generated from combined grammars. | Boolean | optional | <code>False</code> |
-| <a id="antlr-debug"></a>debug | Generate a parser that emits debugging events. | Boolean | optional | <code>False</code> |
-| <a id="antlr-depend"></a>depend | Generate file dependencies; don't actually run antlr. | Boolean | optional | <code>False</code> |
-| <a id="antlr-dfa"></a>dfa | Generate a DFA for each decision point. | Boolean | optional | <code>False</code> |
-| <a id="antlr-dump"></a>dump | Print out the grammar without actions. | Boolean | optional | <code>False</code> |
-| <a id="antlr-imports"></a>imports | The grammar and .tokens files to import. Must be all in the same directory. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> |
-| <a id="antlr-language"></a>language | The code generation target language. Either C, Cpp, CSharp2, CSharp3, JavaScript, Java, ObjC, Python, Python3 or Ruby (case-sensitive). | String | optional | <code>""</code> |
-| <a id="antlr-message_format"></a>message_format | Specify output style for messages. | String | optional | <code>""</code> |
-| <a id="antlr-nfa"></a>nfa | Generate an NFA for each rule. | Boolean | optional | <code>False</code> |
-| <a id="antlr-package"></a>package | The package/namespace for the generated code. | String | optional | <code>""</code> |
-| <a id="antlr-profile"></a>profile | Generate a parser that computes profiling information. | Boolean | optional | <code>False</code> |
-| <a id="antlr-report"></a>report | Print out a report about the grammar(s) processed. | Boolean | optional | <code>False</code> |
-| <a id="antlr-trace"></a>trace | Generate a parser with trace output. If the default output is not enough, you can override the traceIn and traceOut methods. | Boolean | optional | <code>False</code> |
+| <a id="antlr-Xconversiontimeout"></a>Xconversiontimeout | Set NFA conversion timeout for each decision. | Integer | optional | `0` |
+| <a id="antlr-Xdbgconversion"></a>Xdbgconversion | Dump lots of info during NFA conversion. | Boolean | optional | `False` |
+| <a id="antlr-Xdbgst"></a>Xdbgst | Put tags at start/stop of all templates in output. | Boolean | optional | `False` |
+| <a id="antlr-Xdfa"></a>Xdfa | Print DFA as text. | Boolean | optional | `False` |
+| <a id="antlr-Xdfaverbose"></a>Xdfaverbose | Generate DFA states in DOT with NFA configs. | Boolean | optional | `False` |
+| <a id="antlr-Xgrtree"></a>Xgrtree | Print the grammar AST. | Boolean | optional | `False` |
+| <a id="antlr-Xm"></a>Xm | Max number of rule invocations during conversion. | Integer | optional | `0` |
+| <a id="antlr-Xmaxdfaedges"></a>Xmaxdfaedges | Max "comfortable" number of edges for single DFA state. | Integer | optional | `0` |
+| <a id="antlr-Xmaxinlinedfastates"></a>Xmaxinlinedfastates | Max DFA states before table used rather than inlining. | Integer | optional | `0` |
+| <a id="antlr-Xminswitchalts"></a>Xminswitchalts | Don't generate switch() statements for dfas smaller than given number. | Integer | optional | `0` |
+| <a id="antlr-Xmultithreaded"></a>Xmultithreaded | Run the analysis in 2 threads. | Boolean | optional | `False` |
+| <a id="antlr-Xnfastates"></a>Xnfastates | For nondeterminisms, list NFA states for each path. | Boolean | optional | `False` |
+| <a id="antlr-Xnocollapse"></a>Xnocollapse | Collapse incident edges into DFA states. | Boolean | optional | `False` |
+| <a id="antlr-Xnomergestopstates"></a>Xnomergestopstates | Max DFA states before table used rather than inlining. | Boolean | optional | `False` |
+| <a id="antlr-Xnoprune"></a>Xnoprune | Do not test EBNF block exit branches. | Boolean | optional | `False` |
+| <a id="antlr-XsaveLexer"></a>XsaveLexer | For nondeterminisms, list NFA states for each path. | Boolean | optional | `False` |
+| <a id="antlr-Xwatchconversion"></a>Xwatchconversion | Don't delete temporary lexers generated from combined grammars. | Boolean | optional | `False` |
+| <a id="antlr-debug"></a>debug | Generate a parser that emits debugging events. | Boolean | optional | `False` |
+| <a id="antlr-depend"></a>depend | Generate file dependencies; don't actually run antlr. | Boolean | optional | `False` |
+| <a id="antlr-dfa"></a>dfa | Generate a DFA for each decision point. | Boolean | optional | `False` |
+| <a id="antlr-dump"></a>dump | Print out the grammar without actions. | Boolean | optional | `False` |
+| <a id="antlr-imports"></a>imports | The grammar and .tokens files to import. Must be all in the same directory. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` |
+| <a id="antlr-language"></a>language | The code generation target language. Either C, Cpp, CSharp2, CSharp3, JavaScript, Java, ObjC, Python, Python3 or Ruby (case-sensitive). | String | optional | `""` |
+| <a id="antlr-message_format"></a>message_format | Specify output style for messages. | String | optional | `""` |
+| <a id="antlr-nfa"></a>nfa | Generate an NFA for each rule. | Boolean | optional | `False` |
+| <a id="antlr-package"></a>package | The package/namespace for the generated code. | String | optional | `""` |
+| <a id="antlr-profile"></a>profile | Generate a parser that computes profiling information. | Boolean | optional | `False` |
+| <a id="antlr-report"></a>report | Print out a report about the grammar(s) processed. | Boolean | optional | `False` |
+| <a id="antlr-trace"></a>trace | Generate a parser with trace output. If the default output is not enough, you can override the traceIn and traceOut methods. | Boolean | optional | `False` |
diff --git a/test/testdata/java_basic_test/golden.md b/test/testdata/java_basic_test/golden.md
index a6d0818..e98bbd6 100755
--- a/test/testdata/java_basic_test/golden.md
+++ b/test/testdata/java_basic_test/golden.md
@@ -19,7 +19,7 @@
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="java_related_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
| <a id="java_related_rule-first"></a>first | - | <a href="https://bazel.build/concepts/labels">Label</a> | required | |
-| <a id="java_related_rule-fourth"></a>fourth | - | Boolean | optional | <code>False</code> |
+| <a id="java_related_rule-fourth"></a>fourth | - | Boolean | optional | `False` |
| <a id="java_related_rule-second"></a>second | - | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required | |
| <a id="java_related_rule-third"></a>third | - | <a href="https://bazel.build/concepts/labels">Label</a> | required | |
diff --git a/test/testdata/macro_kwargs_test/golden.md b/test/testdata/macro_kwargs_test/golden.md
index d2af867..1a9df5b 100755
--- a/test/testdata/macro_kwargs_test/golden.md
+++ b/test/testdata/macro_kwargs_test/golden.md
@@ -44,7 +44,7 @@
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="macro_with_both-name"></a>name | The name of the test rule. | none |
-| <a id="macro_with_both-number"></a>number | Some number used for important things | <code>3</code> |
+| <a id="macro_with_both-number"></a>number | Some number used for important things | `3` |
| <a id="macro_with_both-args"></a>args | Other arguments to include | none |
| <a id="macro_with_both-kwargs"></a>kwargs | Other attributes to include | none |
@@ -77,7 +77,7 @@
| :------------- | :------------- | :------------- |
| <a id="macro_with_kwargs-name"></a>name | The name of the test rule. | none |
| <a id="macro_with_kwargs-config"></a>config | Config to use for my macro | none |
-| <a id="macro_with_kwargs-deps"></a>deps | List of my macro's dependencies | <code>[]</code> |
+| <a id="macro_with_kwargs-deps"></a>deps | List of my macro's dependencies | `[]` |
| <a id="macro_with_kwargs-kwargs"></a>kwargs | Other attributes to include | none |
**RETURNS**
diff --git a/test/testdata/misc_apis_test/golden.md b/test/testdata/misc_apis_test/golden.md
index 34686ee..1a6b867 100755
--- a/test/testdata/misc_apis_test/golden.md
+++ b/test/testdata/misc_apis_test/golden.md
@@ -18,11 +18,11 @@
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="my_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
-| <a id="my_rule-deps"></a>deps | A list of dependencies. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> |
-| <a id="my_rule-src"></a>src | The source file. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>None</code> |
+| <a id="my_rule-deps"></a>deps | A list of dependencies. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` |
+| <a id="my_rule-src"></a>src | The source file. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` |
| <a id="my_rule-out"></a>out | The output file. | <a href="https://bazel.build/concepts/labels">Label</a> | required | |
-| <a id="my_rule-extra_arguments"></a>extra_arguments | - | List of strings | optional | <code>[]</code> |
-| <a id="my_rule-tool"></a>tool | The location of the tool to use. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>//foo/bar/baz:target</code> |
+| <a id="my_rule-extra_arguments"></a>extra_arguments | - | List of strings | optional | `[]` |
+| <a id="my_rule-tool"></a>tool | The location of the tool to use. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `//foo/bar/baz:target` |
<a id="MyInfo"></a>
diff --git a/test/testdata/namespace_test/golden.md b/test/testdata/namespace_test/golden.md
index 850dcf1..6e4c453 100755
--- a/test/testdata/namespace_test/golden.md
+++ b/test/testdata/namespace_test/golden.md
@@ -37,7 +37,7 @@
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="my_namespace.join_strings-strings"></a>strings | A list of strings to join. | none |
-| <a id="my_namespace.join_strings-delimiter"></a>delimiter | The delimiter to use | <code>", "</code> |
+| <a id="my_namespace.join_strings-delimiter"></a>delimiter | The delimiter to use | `", "` |
**RETURNS**
diff --git a/test/testdata/providers_for_attributes_test/golden.md b/test/testdata/providers_for_attributes_test/golden.md
index 24ebf27..a427cf2 100755
--- a/test/testdata/providers_for_attributes_test/golden.md
+++ b/test/testdata/providers_for_attributes_test/golden.md
@@ -18,12 +18,12 @@
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="my_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
-| <a id="my_rule-fifth"></a>fifth | - | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>None</code> |
-| <a id="my_rule-first"></a>first | this is the first attribute. | <a href="https://bazel.build/rules/lib/dict">Dictionary: Label -> String</a> | optional | <code>{}</code> |
-| <a id="my_rule-fourth"></a>fourth | - | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>None</code> |
-| <a id="my_rule-second"></a>second | - | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> |
-| <a id="my_rule-sixth"></a>sixth | - | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>None</code> |
-| <a id="my_rule-third"></a>third | - | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>None</code> |
+| <a id="my_rule-fifth"></a>fifth | - | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` |
+| <a id="my_rule-first"></a>first | this is the first attribute. | <a href="https://bazel.build/rules/lib/dict">Dictionary: Label -> String</a> | optional | `{}` |
+| <a id="my_rule-fourth"></a>fourth | - | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` |
+| <a id="my_rule-second"></a>second | - | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` |
+| <a id="my_rule-sixth"></a>sixth | - | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` |
+| <a id="my_rule-third"></a>third | - | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` |
<a id="MyProviderInfo"></a>
diff --git a/test/testdata/pure_markdown_template_test/golden.md b/test/testdata/pure_markdown_template_test/golden.md
index 83a0e5c..cedeaf1 100644
--- a/test/testdata/pure_markdown_template_test/golden.md
+++ b/test/testdata/pure_markdown_template_test/golden.md
@@ -18,8 +18,8 @@
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="example_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
-| <a id="example_rule-first"></a>first | This is the first attribute | String | optional | <code>""</code> |
-| <a id="example_rule-second"></a>second | - | String | optional | <code>"2"</code> |
+| <a id="example_rule-first"></a>first | This is the first attribute | String | optional | `""` |
+| <a id="example_rule-second"></a>second | - | String | optional | `"2"` |
<a id="ExampleProviderInfo"></a>
@@ -58,7 +58,7 @@
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="example_function-foo"></a>foo | This parameter does foo related things. | none |
-| <a id="example_function-bar"></a>bar | This parameter does bar related things.<br><br>For example, it does things that require **multiple paragraphs** to explain.<br><br>Note: we should preserve the nested indent in the following code:<br><br><pre><code>json { "key": "value" } </code></pre> | <code>"bar"</code> |
+| <a id="example_function-bar"></a>bar | This parameter does bar related things.<br><br>For example, it does things that require **multiple paragraphs** to explain.<br><br>Note: we should preserve the nested indent in the following code:<br><br><pre><code>json { "key": "value" } </code></pre> | `"bar"` |
<a id="example_aspect"></a>
@@ -85,8 +85,8 @@
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
-| <a id="example_aspect-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
-| <a id="example_aspect-first"></a>first | - | <a href="https://bazel.build/concepts/labels">Label</a> | required | |
-| <a id="example_aspect-second"></a>second | This is the second attribute. | String | optional | <code>""</code> |
+| <a id="example_aspect-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
+| <a id="example_aspect-first"></a>first | - | <a href="https://bazel.build/concepts/labels">Label</a> | required | |
+| <a id="example_aspect-second"></a>second | This is the second attribute. | String | optional | `""` |
diff --git a/test/testdata/py_rule_test/golden.md b/test/testdata/py_rule_test/golden.md
index 0550bf9..d2a8394 100755
--- a/test/testdata/py_rule_test/golden.md
+++ b/test/testdata/py_rule_test/golden.md
@@ -18,11 +18,11 @@
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="py_related_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
-| <a id="py_related_rule-fifth"></a>fifth | Hey look, its the fifth thing! | Boolean | optional | <code>True</code> |
+| <a id="py_related_rule-fifth"></a>fifth | Hey look, its the fifth thing! | Boolean | optional | `True` |
| <a id="py_related_rule-first"></a>first | this is the first doc string! | <a href="https://bazel.build/concepts/labels">Label</a> | required | |
-| <a id="py_related_rule-fourth"></a>fourth | the fourth doc string. | Boolean | optional | <code>False</code> |
+| <a id="py_related_rule-fourth"></a>fourth | the fourth doc string. | Boolean | optional | `False` |
| <a id="py_related_rule-second"></a>second | - | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required | |
-| <a id="py_related_rule-sixth"></a>sixth | it's the sixth thing. | List of integers | optional | <code>[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]</code> |
+| <a id="py_related_rule-sixth"></a>sixth | it's the sixth thing. | List of integers | optional | `[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]` |
| <a id="py_related_rule-third"></a>third | - | <a href="https://bazel.build/concepts/labels">Label</a> | required | |
diff --git a/test/testdata/repo_rules_test/golden.md b/test/testdata/repo_rules_test/golden.md
index da8a1ba..639b5c7 100755
--- a/test/testdata/repo_rules_test/golden.md
+++ b/test/testdata/repo_rules_test/golden.md
@@ -19,6 +19,6 @@
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="my_repo-name"></a>name | A unique name for this repository. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
| <a id="my_repo-repo_mapping"></a>repo_mapping | A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.<p>For example, an entry <code>"@foo": "@bar"</code> declares that, for any time this repository depends on <code>@foo</code> (such as a dependency on <code>@foo//some:target</code>, it should actually resolve that dependency within globally-declared <code>@bar</code> (<code>@bar//some:target</code>). | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required | |
-| <a id="my_repo-useless"></a>useless | This argument will be ignored. You don't have to specify it, but you may. | String | optional | <code>"ignoreme"</code> |
+| <a id="my_repo-useless"></a>useless | This argument will be ignored. You don't have to specify it, but you may. | String | optional | `"ignoreme"` |
diff --git a/test/testdata/simple_test/golden.md b/test/testdata/simple_test/golden.md
index b203bd2..a5a2e39 100755
--- a/test/testdata/simple_test/golden.md
+++ b/test/testdata/simple_test/golden.md
@@ -19,7 +19,7 @@
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="my_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
| <a id="my_rule-first"></a>first | first doc string | <a href="https://bazel.build/concepts/labels">Label</a> | required | |
-| <a id="my_rule-fourth"></a>fourth | fourth doc string | Boolean | optional | <code>False</code> |
+| <a id="my_rule-fourth"></a>fourth | fourth doc string | Boolean | optional | `False` |
| <a id="my_rule-second"></a>second | - | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required | |
| <a id="my_rule-third"></a>third | - | <a href="https://bazel.build/concepts/labels">Label</a> | required | |
diff --git a/test/testdata/struct_default_value_test/golden.md b/test/testdata/struct_default_value_test/golden.md
index 6d07214..38f9908 100755
--- a/test/testdata/struct_default_value_test/golden.md
+++ b/test/testdata/struct_default_value_test/golden.md
@@ -18,10 +18,10 @@
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
-| <a id="check_struct_default_values-struct_no_args"></a>struct_no_args | struct with no arguments | <code>struct()</code> |
-| <a id="check_struct_default_values-struct_arg"></a>struct_arg | struct with one argument | <code>struct(foo = "bar")</code> |
-| <a id="check_struct_default_values-struct_args"></a>struct_args | struct with multiple arguments | <code>struct(bar = "foo", foo = "bar")</code> |
-| <a id="check_struct_default_values-struct_int_args"></a>struct_int_args | struct with int arguments | <code>struct(one = 1, three = 3, two = 2)</code> |
-| <a id="check_struct_default_values-struct_struct_args"></a>struct_struct_args | struct with struct arguments | <code>struct(multiple = struct(one = 1, three = 3, two = 2), none = struct(), one = struct(foo = "bar"))</code> |
+| <a id="check_struct_default_values-struct_no_args"></a>struct_no_args | struct with no arguments | `struct()` |
+| <a id="check_struct_default_values-struct_arg"></a>struct_arg | struct with one argument | `struct(foo = "bar")` |
+| <a id="check_struct_default_values-struct_args"></a>struct_args | struct with multiple arguments | `struct(bar = "foo", foo = "bar")` |
+| <a id="check_struct_default_values-struct_int_args"></a>struct_int_args | struct with int arguments | `struct(one = 1, three = 3, two = 2)` |
+| <a id="check_struct_default_values-struct_struct_args"></a>struct_struct_args | struct with struct arguments | `struct(multiple = struct(one = 1, three = 3, two = 2), none = struct(), one = struct(foo = "bar"))` |
