diff options
| -rw-r--r-- | Makefile.am | 13 | ||||
| -rw-r--r-- | man/blogc-toctree.7.ronn | 87 | ||||
| -rw-r--r-- | man/index.txt | 1 |
3 files changed, 101 insertions, 0 deletions
diff --git a/Makefile.am b/Makefile.am index 8eae1d3..9471577 100644 --- a/Makefile.am +++ b/Makefile.am @@ -313,6 +313,7 @@ EXTRA_DIST += \ man/blogcfile.5.ronn \ man/blogc-source.7.ronn \ man/blogc-template.7.ronn \ + man/blogc-toctree.7.ronn \ man/blogc-pagination.7.ronn \ man/index.txt \ blogc-git-receiver.1 \ @@ -325,6 +326,7 @@ dist_man_MANS = \ blogc.1 \ blogc-source.7 \ blogc-template.7 \ + blogc-toctree.7 \ blogc-pagination.7 \ $(NULL) @@ -409,6 +411,14 @@ blogc-template.7: man/blogc-template.7.ronn --manual "$(PACKAGE_NAME) Manual" \ $(top_srcdir)/man/blogc-template.7.ronn > blogc-template.7 +blogc-toctree.7: man/blogc-toctree.7.ronn + $(AM_V_GEN)$(RONN) \ + --roff \ + --pipe \ + --organization "Rafael G. Martins" \ + --manual "$(PACKAGE_NAME) Manual" \ + $(top_srcdir)/man/blogc-toctree.7.ronn > blogc-toctree.7 + blogc-pagination.7: man/blogc-pagination.7.ronn $(AM_V_GEN)$(RONN) \ --roff \ @@ -437,6 +447,9 @@ blogc-source.7: blogc-template.7: $(AM_V_GEN)echo "error: ronn not found. failed to build man page: $@"; exit 1 +blogc-toctree.7: + $(AM_V_GEN)echo "error: ronn not found. failed to build man page: $@"; exit 1 + blogc-pagination.7: $(AM_V_GEN)echo "error: ronn not found. failed to build man page: $@"; exit 1 diff --git a/man/blogc-toctree.7.ronn b/man/blogc-toctree.7.ronn new file mode 100644 index 0000000..720a4ee --- /dev/null +++ b/man/blogc-toctree.7.ronn @@ -0,0 +1,87 @@ +blogc-toctree(7) -- blogc's "table of contents" tree support +============================================================ + +## DESCRIPTION + +blogc(1) generates a "table of contents" tree for every source file, out of +its content headers, that is available for usage as a `{{ TOCTREE }}` +template variable. The tree is composed by lists of links for the headers, +and is usually placed right before the content, as an index. + +## USAGE + +For a source file with the following content: + + TITLE: Some Title + ----------------- + # Header 1 + + Some content. + + ## Header 2 + + More content. + + ### Header 3 + + Content. + +A template block with the following content: + + {% block entry %} + {{ TOCTREE }} + {% endblock %} + +Would generate output similar to this: + + <ul> + <li><a href="#header-1">Header 1</a></li> + <ul> + <li><a href="#header-2">Header 2</a></li> + <ul> + <li><a href="#header-3">Header 3</a></li> + </ul> + </ul> + </ul> + +The depth of the tree can be controlled using the `TOCTREE_MAXDEPTH` variable, +that may be defined globally (see blogc(1)) or for each source file (see +blogc-source(7)). Setting this variable to `0` disables the generator. +Setting this variable to a positive number will limit the number of tree +levels to such value. The default value is `-1`, which means no maximum depth. + +Please note that the depth is evaluated from the lower header level available +in the content. This means that if a source file only have level 2 and level 3 +headers, and `TOCTREE_MAXDEPTH=1`, only headers with level 2 are included in the +"table of contents" tree. + +For a source file with the following content: + + TITLE: Some Title + TOCTREE_MAXDEPTH: 1 + ----------------- + ## Header 2 + + Some content + + ### Header 3 + + More content + +With the same template presented before, would generate output similar to this: + + <ul> + <li><a href="#header-2">Header 2</a></li> + </ul> + +## BUGS + +Please report any issues to: <https://github.com/blogc/blogc> + +## AUTHOR + +Rafael G. Martins <<rafael@rafaelmartins.eng.br>> + +## SEE ALSO + +blogc(1), blogc-source(7), blogc-template(7) diff --git a/man/index.txt b/man/index.txt index a68646a..d11e1c9 100644 --- a/man/index.txt +++ b/man/index.txt @@ -6,6 +6,7 @@ blogc-runserver(1) blogc-runserver.1.ronn blogcfile(5) blogcfile.5.ronn blogc-source(7) blogc-source.7.ronn blogc-template(7) blogc-template.7.ronn +blogc-toctree(7) blogc-toctree.7.ronn blogc-pagination(7) blogc-pagination.7.ronn # external manuals |