Document #3032

Signed-off-by: Chris Warrick <kwpolska@gmail.com>
getnikola · Apr 15, 2018 · d792c08 · d792c08
1 parent c962f86
commit d792c08
Show file tree

Hide file tree

Showing 3 changed files with 92 additions and 84 deletions.
diff --git a/CHANGES.txt b/CHANGES.txt
@@ -4,6 +4,7 @@ New in master
 Features
 --------
 
+* Add support for fragments in path handlers (Issue #3032)
 * Recognize both TEASER_END and (new) END_TEASER (Issue #3010)
 * New MARKDOWN_EXTENSION_CONFIGS setting (Issue #2970)
 * Replace ``flowr.js`` with ``justified-layout.js`` by Flickr

diff --git a/docs/path_handlers.rst b/docs/path_handlers.rst
@@ -2,252 +2,254 @@
 .. slug: path-handlers
 .. author: The Nikola Team
 
+.. DO NOT EDIT, this file is auto-generated by scripts/document_path_handlers.py
+
 Nikola supports special links with the syntax ``link://kind/name``. In
-templates you can also use ``_link(kind, name)``. You can add
-fragments (``#anchor``) and  query strings (``?key=value``) for extra
-arguments, or pass keyword arguments to ``_link`` in templates (support and
-behavior depends on path handlers themselves)
+templates you can also use ``_link(kind, name)``.  You can add query strings
+(``?key=value``) for extra arguments, or pass keyword arguments to ``_link`` in
+templates (support and behavior depends on path handlers themselves). Fragments
+(``#anchor``) will be appended to the transformed link.
 
 Here are the descriptions for all the supported kinds.
 
 .. class:: dl-horizontal
 
 archive
     Link to archive path, name is the year.
-
+    
     Example:
-
+    
     link://archive/2013 => /archives/2013/index.html
 
 archive_atom
     Link to archive Atom path, name is the year (archive pages must be indexes).
-
+    
     Example:
-
+    
     link://archive_atom/2013 => /archives/2013/index.atom
 
 author
     Link to an author's page.
-
+    
     Example:
-
+    
     link://author/joe => /authors/joe.html
 
 author_atom
     Link to an author's Atom feed.
-
+    
     Example:
-
+    
     link://author_atom/joe => /authors/joe.atom
 
 author_index
     Link to the authors index.
-
+    
     Example:
-
+    
     link://authors/ => /authors/index.html
 
 author_rss
     Link to an author's RSS feed.
-
+    
     Example:
-
+    
     link://author_rss/joe => /authors/joe.xml
 
 category
     A link to a category. Takes page number as optional keyword argument.
-
+    
     Example:
-
+    
     link://category/dogs => /categories/dogs.html
 
 category_atom
     A link to a category's Atom feed.
-
+    
     Example:
-
+    
     link://category_atom/dogs => /categories/dogs.atom
 
 category_index
     A link to the category index.
-
+    
     Example:
-
+    
     link://category_index => /categories/index.html
 
 category_rss
     A link to a category's RSS feed.
-
+    
     Example:
-
+    
     link://category_rss/dogs => /categories/dogs.xml
 
 filename
     Link to post or page by source filename.
-
+    
     Example:
-
+    
     link://filename/manual.txt => /docs/handbook.html
-
+    
 
 gallery
     Link to an image gallery's path.
-
+    
     It will try to find a gallery with that name if it's not ambiguous
     or with that path. For example:
-
+    
     link://gallery/london => /galleries/trips/london/index.html
-
+    
     link://gallery/trips/london => /galleries/trips/london/index.html
-
+    
 
 gallery_global
     Link to the global gallery path, which contains all the images in galleries.
-
+    
     There is only one copy of an image on multilingual blogs, in the site root.
-
+    
     link://gallery_global/london => /galleries/trips/london/index.html
-
+    
     link://gallery_global/trips/london => /galleries/trips/london/index.html
-
+    
     (a ``gallery`` link could lead to eg. /en/galleries/trips/london/index.html)
-
+    
 
 gallery_rss
     Link to an image gallery's RSS feed.
-
+    
     It will try to find a gallery with that name if it's not ambiguous
     or with that path. For example:
-
+    
     link://gallery_rss/london => /galleries/trips/london/rss.xml
-
+    
     link://gallery_rss/trips/london => /galleries/trips/london/rss.xml
-
+    
 
 index
     Link to a numbered index.
-
+    
     Example:
-
+    
     link://index/3 => /index-3.html
 
 index_atom
     Link to a numbered Atom index.
-
+    
     Example:
-
+    
     link://index_atom/3 => /index-3.atom
 
 index_rss
     A link to the RSS feed path.
-
+    
     Example:
-
+    
     link://rss => /blog/rss.xml
 
 listing
     Return a link to a listing.
-
+    
     It will try to use the file name if it's not ambiguous, or the file path.
-
+    
     Example:
-
+    
     link://listing/hello.py => /listings/tutorial/hello.py.html
-
+    
     link://listing/tutorial/hello.py => /listings/tutorial/hello.py.html
-
+    
 
 listing_source
     Return a link to the source code for a listing.
-
+    
     It will try to use the file name if it's not ambiguous, or the file path.
-
+    
     Example:
-
+    
     link://listing_source/hello.py => /listings/tutorial/hello.py
-
+    
     link://listing_source/tutorial/hello.py => /listings/tutorial/hello.py
-
+    
 
 post_path
     Link to the destination of an element in the POSTS/PAGES settings.
-
+    
     Example:
-
+    
     link://post_path/posts => /blog
-
+    
 
 root
     Link to the current language's root.
-
+    
     Example:
-
+    
     link://root_path => /
-
+    
     link://root_path => /translations/spanish/
-
+    
 
 rss
     A link to the RSS feed path.
-
+    
     Example:
-
+    
     link://rss => /blog/rss.xml
 
 section_index
     Link to the index for a section.
-
+    
     Example:
-
+    
     link://section_index/cars => /cars/index.html
 
 section_index_atom
     Link to the Atom index for a section.
-
+    
     Example:
-
+    
     link://section_index_atom/cars => /cars/index.atom
 
 section_index_rss
     Link to the RSS feed for a section.
-
+    
     Example:
-
+    
     link://section_index_rss/cars => /cars/rss.xml
 
 slug
     Return a link to a post with given slug, if not ambiguous.
-
+    
     Example:
-
+    
     link://slug/yellow-camaro => /posts/cars/awful/yellow-camaro/index.html
-
+    
 
 tag
     A link to a tag's page. Takes page number as optional keyword argument.
-
+    
     Example:
-
+    
     link://tag/cats => /tags/cats.html
 
 tag_atom
     A link to a tag's Atom feed.
-
+    
     Example:
-
+    
     link://tag_atom/cats => /tags/cats.atom
 
 tag_index
     A link to the tag index.
-
+    
     Example:
-
+    
     link://tag_index => /tags/index.html
 
 tag_rss
     A link to a tag's RSS feed.
-
+    
     Example:
-
+    
     link://tag_rss/cats => /tags/cats.xml
 
diff --git a/scripts/document_path_handlers.py b/scripts/document_path_handlers.py
@@ -8,8 +8,13 @@
 .. slug: path-handlers
 .. author: The Nikola Team
 
-Nikola supports special links with the syntax ``link://kind/name``. In the templates you can also use ``_link(kind, name)``.
-You can also add query strings (``?key=value``) for extra arguments, or pass keyword arguments to ``_link`` in templates (support and behavior depends on path handlers themselves)
+.. DO NOT EDIT, this file is auto-generated by scripts/document_path_handlers.py
+
+Nikola supports special links with the syntax ``link://kind/name``. In
+templates you can also use ``_link(kind, name)``.  You can add query strings
+(``?key=value``) for extra arguments, or pass keyword arguments to ``_link`` in
+templates (support and behavior depends on path handlers themselves). Fragments
+(``#anchor``) will be appended to the transformed link.
 
 Here are the descriptions for all the supported kinds.