App::DocKnot::Spin::Sitemap - Generate page navigation links for spin

Author

       Russ Allbery <rra@cpan.org>

Class Methods

       new(PATH)
           Create a new App::DocKnot::Spin::Sitemap object for the .sitemap file specified by PATH.

Copyright And License

       Copyright 1999-2000, 2002-2004, 2008, 2021-2022 Russ Allbery <rra@cpan.org>

       Permission is hereby granted, free of charge, to any  person  obtaining  a  copy  of  this  software  and
       associated  documentation  files (the "Software"), to deal in the Software without restriction, including
       without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,  and/or  sell
       copies  of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
       following conditions:

       The above copyright notice and this permission notice shall be included  in  all  copies  or  substantial
       portions of the Software.

       THE  SOFTWARE  IS  PROVIDED  "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
       LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND  NONINFRINGEMENT.   IN
       NO  EVENT  SHALL  THE  AUTHORS  OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
       WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT  OF  OR  IN  CONNECTION  WITH  THE
       SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Description

App::DocKnot::Spin supports sitemap information stored in a ".sitemap" file at the top of the source
directory. If this is present, it is used to add navigation information to every generated page.

App::DocKnot::Spin::Sitemap encapsulates parsing of that file and generating the HTML for inter-page
links. It can also generate HTML for the entirety of the sitemap to support the "\sitemap" thread
command.

The format of this file is one line per web page, with indentation showing the tree structure. Each line
should be formatted as a partial URL (relative to the top of the site) starting with "/", a colon, and a
page description. The partial URL should be for the generated pages, not the source files (so, for
example, should use an ".html" extension). The top of the generated site should have the URL of "/" at
the top of the sitemap.

If two pages at the same level aren't related and shouldn't have next and previous links to each other,
they should be separated by three dashes on a line by themselves at the same indentation level.

Here's an example of a simple .sitemap file:

/personal/: Personal Information
/personal/contact.html: Contact Information
---
/personal/projects.html: Current Projects
/links/: Links
/links/lit.html: Other Literature
/links/music.html: Music
/links/sf.html: Science Fiction and Fantasy

This defines two sub-pages of the top page, "/personal/" and "/links/". "/personal/" has two pages under
it that are not part of the same set and therefore shouldn't have links to each other. "/links/" has
three pages under it which are part of a set and should be linked between each other.

Instance Methods

       links(PAGE)
           Generate  the  "<link>"  tags for the provided PAGE, which should be a URL relative to the top of the
           generated site and starting with "/".  The return value is a  list  of  lines  to  add  to  the  HTML
           "<head>" section, or an empty list if the page was not found in the sitemap.

       navbar(PAGE)
           Generate  the  navigation bar for the provided PAGE, which should be a URL relative to the top of the
           generated site and starting with "/".  The return  value  is  a  list  of  HTML  lines  suitable  for
           injecting into the output page.

       sitemap()
           Return  the  sitemap  as a list of lines of formatted HTML, suitable for inclusion in a generated web
           page.  This is used to implement the "\sitemap" thread command.

Name

       App::DocKnot::Spin::Sitemap - Generate page navigation links for spin

Requirements

       Perl 5.24 or later and the List::SomeUtils and Path::Tiny modules, both of which are available from CPAN.

Synopsis

           use App::DocKnot::Spin::Sitemap;
           my $sitemap = App::DocKnot::Spin::Sitemap->new('/path/to/.sitemap');
           my @links = $sitemap->links('some/output/page.html');
           my @navbar = $sitemap->navbar('some/output/page.html');