[
https://issues.apache.org/jira/browse/SAMZA-297?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14038517#comment-14038517
]
Yan Fang commented on SAMZA-297:
--------------------------------
Tested the patch and added few comments in RB. Thank you.
> 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
> Attachments: SAMZA-297.1.patch
>
>
> 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)
