Martin Kleppmann created SAMZA-297:
--------------------------------------
Summary: Allow linking to sub-headings in the documentation
Key: SAMZA-297
URL: https://issues.apache.org/jira/browse/SAMZA-297
Project: Samza
Issue Type: Improvement
Reporter: Martin Kleppmann
Assignee: Martin Kleppmann
Some of the documentation pages are quite long, so for cross-references in the
docs, it's useful to be able to link to sub-headings within a page.
Jekyll/Redcarpet supports this with the "with_toc_data" option, which we have
enabled.
However, different versions of the Redcarpet gem treat that option differently.
The latest version generates an ID based on the text of the heading, for
example:
{noformat}
<h4 id="log4j-configuration">Log4j configuration</h4>
{noformat}
whereas older versions generate an ID which is numbered sequentially within the
page:
{noformat}
<h4 id="toc_0">Log4j configuration</h4>
{noformat}
The new behaviour is probably preferable, as it's less susceptible to being
broken if documentation sections are added or reordered. However, this means
that we have to ensure that all committers who build the website are using the
latest version of the gems.
The standard way of enforcing version constraints and dependencies for Ruby
gems is [Bundler|http://bundler.io/]. I propose adding a bundler Gemfile to the
docs directory, which would make that pretty easy.
--
This message was sent by Atlassian JIRA
(v6.2#6252)
