App::D...Sitemap(3pm)

📦
version 8.0.1 · 4 versions
, in ubuntu resolute, ubuntu stonking

💖 App::DocKnot::Spin::Sitemap 💖

okay bestie, listen up — this is the page for App::DocKnot::Spin::Sitemap, a little Perl module from the User Contributed Perl Documentation collection, and it's literally the thing that makes your spin-generated site have ✨navigation✨. sit down, grab a ✨strawberry✨ drink, and let's go.

🌸 NAME 🌸

App::DocKnot::Spin::Sitemap — the module that generates page navigation links for spin. that's it, that's the whole job, and it eats every time 💅

✨ 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');

look at her. iconic. no notes. 🎀

🫶 REQUIREMENTS 🫶

you need:

  • Perl 5.24 or later, bestie, no downgrading 💀
  • the List::SomeUtils module
  • the Path::Tiny module

both modules are available from CPAN, which is giving "go get them right now" energy. 🦋

👑 DESCRIPTION 👑

okay so App::DocKnot::Spin supports sitemap information stored in a .sitemap file at the top of the source directory. if that file is present, it gets used to add navigation information to every generated page. every single one. main character behavior, honestly.

App::DocKnot::Spin::Sitemap encapsulates the parsing of that file and the generating of the HTML for inter-page links. it can also generate HTML for the entirety of the sitemap, which is how the \sitemap thread command gets supported. 🧚

🌈 the .sitemap file format 🌈

the format is one line per web page, and indentation shows the tree structure. pretty. the way that indentation carries the whole hierarchy… it's giving ancient wisdom.

each line should be formatted as:

  1. a partial URL — relative to the top of the site, and starting with /
  2. a colon
  3. a page description

and a really important detail, no cap: the partial URL should be for the generated pages, not the source files. so for example it should use an .html extension. and the top of the generated site should have the URL of / at the top of the sitemap. periodt.

💀 when pages are NOT friends 💀

if two pages at the same level aren't related and shouldn't have next and previous links to each other, separate them with three dashes on a line by themselves, at the same indentation level. that's the "we're not mutuals" divider. 🙈

🍓 a simple .sitemap example 🍓

/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

wait, let me give you that exactly as the manual has it, because precision is mother:

/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

okay so what does that actually mean, bestie?

  • it 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, so they shouldn't have links to each other. (that's the --- doing its thing ✂️)
  • /links/ has three pages under it which are part of a set, so they should be linked between each other. friendship bracelet energy 🫶

🎀 CLASS METHODS 🎀

  • new(PATH) — create a new App::DocKnot::Spin::Sitemap object for the .sitemap file specified by PATH. baby's first constructor ✨

💅 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. (not me getting an empty list and spiralling 😭)
  • 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. inject her. 💉✨
  • sitemap() — return the sitemap as a list of lines of formatted HTML, suitable for inclusion in a generated web page. this is what implements the \sitemap thread command. the whole tree, in HTML, slay 👑

🌟 AUTHOR 🌟

Russ Allbery <rra@cpan.org>

(hey russ, king behavior, we love you 👑)

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.

like, translated to group chat: it's free, use it, but there's no warranty, bestie, so don't come for anybody if it goes sideways 💀

🦋 SEE ALSO 🦋

this module is part of the App-DocKnot distribution. the current version of DocKnot is available from CPAN, or directly from its web site at <https://www.eyrie.org/~eagle/software/docknot/>. go click it, it's right there 🌈

and that's the whole page, bestie!! 💖 this lovely specimen of documentation is from perl v5.40.1, dated 2026-01-16 — yes, that's the version and the date, no cap, and the manual is filed under App::D...Sitemap(3pm) in the User Contributed Perl Documentation. mwah. 😘💅✨

📦 where this page comes from