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

✨ NAME ✨

ok so bestie, meet App::DocKnot::Generate — it's the part of App::DocKnot that generates documentation straight from your package metadata 💅 like it takes your metadata files and your templates and it just… makes the docs for you. iconic behavior tbh.

---

🌸 SYNOPSIS 🌸

use App::DocKnot::Generate;
my $docknot
  = App::DocKnot::Generate->new({ metadata => 'docs/docknot.yaml' });
my $readme = $docknot->generate('readme');
my $index = $docknot->generate('thread');
$docknot->generate_output('readme');
$docknot->generate_output('thread', 'www/index.th')

look at that. no notes. 🫶

---

🎀 REQUIREMENTS 🎀

you're gonna need Perl 5.24 or later, plus these modules: File::BaseDir, File::ShareDir, Kwalify, Path::Tiny, Template (that's part of Template Toolkit, iykyk), and YAML::XS. good news bestie: all of them are available from CPAN ⭐

---

🦋 DESCRIPTION 🦋

so this component of DocKnot is the whole system for generating consistent human-readable software package documentation from metadata files — mostly JSON, plus files that hold documentation snippets. it takes a directory of metadata plus a set of templates as input, and then it generates a documentation file from that metadata, given the template name. literally the glow-up pipeline for your docs 💖

the path to the metadata directory for a package gets passed in as an explicit argument to the App::DocKnot::Generate constructor. that's the only thing you hand it directly. every other bit of data (right now: templates and license information) gets loaded via File::BaseDir, which means it uses XDG paths by default. translation? templates and other global configuration are found by searching these paths, in this exact order:

1. $HOME/.config/docknot
2. $XDG_CONFIG_DIRS/docknot (/etc/xdg/docknot by default)
3. Files included in the package.

default templates and license files ship with the App::DocKnot module, and they get used unless more specific configuration files exist. so you always have a fallback, no cap 🧚

---

👑 CLASS METHODS 👑

💜 new(ARGS)

creates a new App::DocKnot::Generate object. use this one for all your subsequent actions, okay? ARGS should be a hash reference with one or more of these keys:

• metadata — the path to the directory containing metadata for a package. default: docs/docknot.yaml relative to the current directory.
• width — the wrap width to use when generating documentation. default: 74.

---

🔥 INSTANCE METHODS 🔥

⭐ generate(TEMPLATE)

loads the metadata from the path you gave in the constructor, then generates the documentation file defined by TEMPLATE — and TEMPLATE is the name of a template. the template itself gets loaded from the App::DocKnot configuration path, exactly like DESCRIPTION describes. returns the generated documentation file as a string. yes bestie, a string, so you can do whatever you want with it 💅

🌈 generate_all()

generates all of the documentation files for a package. right now that's defined as the "readme" and "readme-md" templates. output gets written to the default output locations, as described under generate_output().

🍓 generate_output(TEMPLATE [, OUTPUT])

same as generate() except instead of returning the generated documentation file as a string, it writes it to the file named by OUTPUT. and if you don't give that argument, a default based on the TEMPLATE argument is chosen like so:

readme     ->  README
readme-md  ->  README.md

heads up bestie: if TEMPLATE isn't one of the templates listed above, the OUTPUT argument is required. no skipping it 🙈

---

✨ AUTHOR ✨

Russ Allbery <rra@cpan.org> — ty for your service king 👑

---

💖 COPYRIGHT AND LICENSE 💖

Copyright 2013-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.

(that's the legal bit, and yes it's giving very serious, keep it exactly as-is bestie 💀)

---

🌟 SEE ALSO 🌟

• docknot(1)
• App::DocKnot::Config

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/>.

---

and that's the whole page, bestie 🎀 this was App::D...nerate(3pm), served up by perl v5.40.1, dated 2026-01-16, from the User Contributed Perl Documentation. go generate something pretty 💅✨