Merge pull request #672 from prometheus/grobie/code-linker

Create links to placeholder definitions in config

Rules

@@ -50,6 +50,7 @@ compile '*' do
     filter :bootstrappify
     filter :admonition
     filter :colorize_syntax, :default_colorizer => :pygmentsrb
+    filter :config_linker if item[:title] == 'Configuration'
     filter :toc, style: item[:toc]
     if item[:kind] == 'article'
       layout 'blog'

content/docs/alerting/configuration.md

@@ -97,7 +97,7 @@ inhibit_rules:
 ```
 
 
-## Route `<route>`
+## `<route>`
 
 A route block defines a node in a routing tree and its children. Its optional
 configuration parameters are inherited from its parent node if not set.
@@ -177,7 +177,7 @@ route:
 
 
 
-## Inhibit rule `<inhibit_rule>`
+## `<inhibit_rule>`
 
 An inhibition rule is a rule that mutes an alert matching a set of matchers
 under the condition that an alert exists that matches another set of matchers.
@@ -204,7 +204,7 @@ source_match_re:
 ```
 
 
-## Receiver `<receiver>`
+## `<receiver>`
 
 Receiver is a named configuration of one or more notification integrations.
 
@@ -234,7 +234,7 @@ webhook_configs:
 ```
 
 
-## Email receiver `<email_config>`
+## `<email_config>`
 
 ```
 # Whether or not to notify about resolved alerts.
@@ -262,7 +262,7 @@ to: <tmpl_string>
 [ headers: { <string>: <tmpl_string>, ... } ]
 ```
 
-## HipChat receiver `<hipchat_config>`
+## `<hipchat_config>`
 
 HipChat notifications use a [Build Your Own](https://confluence.atlassian.com/hc/integrations-with-hipchat-server-683508267.html) integration.
 
@@ -290,7 +290,7 @@ room_id: <tmpl_string>
 [ color:  <tmpl_string> | default = '{{ if eq .Status "firing" }}red{{ else }}green{{ end }}' ]
 ```
 
-## PagerDuty receiver `<pagerduty_config>`
+## `<pagerduty_config>`
 
 PagerDuty notifications are sent via the [PagerDuty API](https://developer.pagerduty.com/documentation/integration/events).
 
@@ -321,7 +321,7 @@ service_key: <tmpl_string>
 } ]
 ```
 
-## Pushover receiver `<pushover_config>`
+## `<pushover_config>`
 
 Pushover notifications are sent via the [Pushover API](https://pushover.net/api).
 
@@ -353,7 +353,7 @@ token: <string>
 [ expire: <duration> | default = 1h ]
 ```
 
-## Slack receiver `<slack_config>`
+## `<slack_config>`
 
 Slack notifications are sent via [Slack webhooks](https://api.slack.com/incoming-webhooks).
 
@@ -380,7 +380,7 @@ channel: <tmpl_string>
 ```
 
 
-## OpsGenie receiver `<opsgenie_config>`
+## `<opsgenie_config>`
 
 OpsGenie notifications are sent via the [OpsGenie API](https://www.opsgenie.com/docs/web-api/alert-api).
 
@@ -410,7 +410,7 @@ api_key: <string>
 ```
 
 
-## Webhook receiver `<webhook_config>`
+## `<webhook_config>`
 
 The webhook receiver allows configuring a generic receiver.
 
@@ -447,4 +447,3 @@ endpoint:
   ]
 }
 ```
-

content/docs/operating/configuration.md

@@ -33,11 +33,15 @@ value is set to the specified default.
 
 Generic placeholders are defined as follows:
 
+* `<boolean>`: a boolean that can take the values `true` or `false`
 * `<duration>`: a duration matching the regular expression `[0-9]+(ms|[smhdwy])`
 * `<labelname>`: a string matching the regular expression `[a-zA-Z_][a-zA-Z0-9_]*`
 * `<labelvalue>`: a string of unicode characters
 * `<filename>`: a valid path in the current working directory
-* `<boolean>`: a boolean that can take the values `true` or `false`
+* `<host>`: a valid string consisting of a hostname or IP followed by an optional port number
+* `<path>`: a valid URL path
+* `<scheme>`: a string that can take the values `http` or `https`
+* `<string>`: a regular string
 
 The other placeholders are specified separately.
 
@@ -77,7 +81,7 @@ alerting:
   alert_relabel_configs:
     [ - <relabel_config> ... ]
   alertmanagers:
-    [- <alertmanager_config> ... ]
+    [ - <alertmanager_config> ... ]
 
 # Settings related to the experimental remote write feature.
 remote_write:
@@ -107,7 +111,7 @@ target and its labels before scraping.
 
 ```
 # The job name assigned to scraped metrics by default.
-job_name: <name>
+job_name: <job_name>
 
 # How frequently to scrape targets from this job.
 [ scrape_interval: <duration> | default = <global_config.scrape_interval> ]
@@ -227,9 +231,7 @@ metric_relabel_configs:
 [ sample_limit: <int> | default = 0 ]
 ```
 
-Where `<scheme>` may be `http` or `https` and `<path>` is a valid URL path.
-`<job_name>` must be unique across all scrape configurations and adhere to the
-regex `[a-zA-Z_][a-zA-Z0-9_-]`.
+Where `<job_name>` must be unique across all scrape configurations.
 
 ### `<tls_config>`
 
@@ -726,6 +728,7 @@ paths:
 Serverset data must be in the JSON format, the Thrift format is not currently supported.
 
 ### `<triton_sd_config>`
+
 CAUTION: Triton SD is in beta: breaking changes to configuration are still
 likely in future releases.
 
@@ -783,10 +786,6 @@ labels:
   [ <labelname>: <labelvalue> ... ]
 ```
 
-Where `<host>` is a valid string consisting of a hostname or IP followed by a port
-number.
-
-
 ### `<relabel_config>`
 
 Relabeling is a powerful tool to dynamically rewrite the label set of a target before
@@ -981,9 +980,8 @@ relabel_configs:
   [ - <relabel_config> ... ]
 ```
 
-Where `<scheme>` may be `http` or `https` and `<path>` is a valid URL path.
-
 ### `<remote_write>`
+
 CAUTION: Remote write is experimental: breaking changes to configuration are
 likely in future releases.
 

lib/filters/config_linker.rb

+# encoding: utf-8
+
+require 'nokogiri'
+
+class ConfigLinker < ::Nanoc::Filter
+  identifier :config_linker
+
+  def run(content, _params = {})
+    doc = Nokogiri::HTML(content)
+    definitions = types(doc.xpath('//code'))
+    configs = doc.xpath('//pre//code')
+
+    configs.each do |config|
+      definitions.each do |text, html|
+        config.inner_html = config.inner_html.gsub(html, %(<a href="##{text}">#{html}</a>))
+      end
+    end
+
+    doc.to_s
+  end
+
+  # types returns a dictionary of all type definitions and their HTML representation.
+  def types(codes)
+    # Select all placeholders.
+    elements = codes.select do |code|
+      code.children.size == 1 && code.text =~ /\A<[^>]+>\Z/
+    end
+
+    # Initialize dictionary with placeholders which are headers, as these are already linked.
+    dict = elements.each_with_object({}) do |e, memo|
+      if e.parent.attr('id') == e.text
+        memo[e.text] = e.inner_html
+      end
+    end
+
+    # Create anchors for the remaining placeholders.
+    elements.each_with_object(dict) do |e, memo|
+      unless memo.include?(e.text)
+        e['id'] = e.text
+        memo[e.text] = e.inner_html
+      end
+    end
+
+    dict
+  end
+end