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

@@ -17,7 +17,7 @@ To view all available command-line flags, run `prometheus -h`.
 
 Prometheus can reload its configuration at runtime. If the new configuration
 is not well-formed, the changes will not be applied.
-A configuration reload is triggered by sending a `SIGHUP` to the Prometheus process or 
+A configuration reload is triggered by sending a `SIGHUP` to the Prometheus process or
 sending a HTTP POST request to the `/-/reload` endpoint.
 This will also reload any configured rule files.
 
@@ -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> ]
@@ -154,7 +158,7 @@ basic_auth:
 # the configured bearer token. It is mutually exclusive with `bearer_token_file`.
 [ bearer_token: <string> ]
 
-# Sets the `Authorization` header on every scrape request with the bearer token 
+# Sets the `Authorization` header on every scrape request with the bearer token
 # read from the configured file. It is mutually exclusive with `bearer_token`.
 [ bearer_token_file: /path/to/bearer/token/file ]
 
@@ -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
@@ -887,13 +886,13 @@ CAUTION: Dynamic discovery of Alertmanager instances is in alpha state. Breaking
 changes may happen in future releases. Use static configuration via the `-alertmanager.url` flag
 as a stable alternative.
 
-An `alertmanager_config` section specifies Alertmanager instances the Prometheus server sends 
+An `alertmanager_config` section specifies Alertmanager instances the Prometheus server sends
 alerts to. It also provides parameters to configure how to communicate with these Alertmanagers.
 
 Alertmanagers may be statically configured via the `static_configs` parameter or
 dynamically discovered using one of the supported service-discovery mechanisms.
 
-Additionally, `relabel_configs` allow selecting Alertmanagers from discovered 
+Additionally, `relabel_configs` allow selecting Alertmanagers from discovered
 entities and provide advanced modifications to the used API path, which is exposed
 through the `__alerts_path__` label.
 
@@ -901,7 +900,7 @@ through the `__alerts_path__` label.
 # Per-target Alertmanager timeout when pushing alerts.
 [ timeout: <duration> | default = 10s ]
 
-# Prefix for the HTTP path alerts are pushed to. 
+# Prefix for the HTTP path alerts are pushed to.
 [ path_prefix: <path> | default = / ]
 
 # Configures the protocol scheme used for requests.
@@ -917,7 +916,7 @@ basic_auth:
 # the configured bearer token. It is mutually exclusive with `bearer_token_file`.
 [ bearer_token: <string> ]
 
-# Sets the `Authorization` header on every request with the bearer token 
+# Sets the `Authorization` header on every request with the bearer token
 # read from the configured file. It is mutually exclusive with `bearer_token`.
 [ bearer_token_file: /path/to/bearer/token/file ]
 
@@ -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