Web::PerlDistSite - generate fairly flashy websites for CPAN distributions
Basically a highly specialized static site generator.
You will need cpanm.
You will need nodejs with npm.
You will need make.
Create a directory and put this Makefile in it:
.PHONY: all all : styles scripts images pages .PHONY: clean clean : rm -fr _build docs .PHONY: install install : npm install cpanm Web::PerlDistSite .PHONY: images images : mkdir -p docs/assets/ cp -r images docs/assets/ .PHONY: styles styles : docs/assets/styles/main.css .PHONY: scripts scripts : docs/assets/scripts/bootstrap.bundle.min.js docs/assets/scripts/bootstrap.bundle.min.js.map .PHONY: pages pages : mkdir -p docs perl -Ilib -MWeb::PerlDistSite::Compile -e write_pages _build/main.scss : perl -Ilib -MWeb::PerlDistSite::Compile -e write_main_scss _build/layout.scss : perl -Ilib -MWeb::PerlDistSite::Compile -e write_layout_scss _build/variables.scss : config.yaml perl -Ilib -MWeb::PerlDistSite::Compile -e write_variables_scss custom.scss : touch -a custom.scss docs/assets/styles/main.css : _build/main.scss _build/variables.scss _build/layout.scss custom.scss mkdir -p docs/assets/styles node node_modules/sass/sass.js --style=compressed _build/main.scss:docs/assets/styles/main.css docs/assets/scripts/bootstrap.bundle.min.js : mkdir -p docs/assets/scripts cp node_modules/bootstrap/dist/js/bootstrap.bundle.min.js docs/assets/scripts/bootstrap.bundle.min.js docs/assets/scripts/bootstrap.bundle.min.js.map : mkdir -p docs/assets/scripts cp node_modules/bootstrap/dist/js/bootstrap.bundle.min.js.map docs/assets/scripts/bootstrap.bundle.min.js.map
And this project.json:
{ "dependencies": { "@popperjs/core": "^2.11.7", "bootstrap": "^5.2.3", "sass": "^1.60.0" } }
Now run make install and the rest of the dependencies will be installed.
make install
Configuration should be via a file config.yaml. This is a YAML file containing a hash with the following keys. Each key is optional, unless noted as required.
theme
A hashref of colour codes. You need at least "primary", "secondary", "light", and "dark". "info", "success", "warning", and "danger" are also allowed.
theme: light: "#e4e3e1" dark: "#32201D" primary: "#763722" secondary: "#E4A042"
name
The name of the project you're building a website for. This is assumed to be a CPAN distribution name, like "Exporter-Tiny" or "Foo-Bar-Baz".
abstract
A short plain-text summary of the project.
abstract_html
A short HTML summary of the project.
copyright
A short plain-text copyright statement for the website footers.
github
Link to a github repo for the site. Expected to be of the form "https://github.com/username/reponame".
issues
Link to an issue tracker.
sponsor
Hashref containing project sponsorship info. The "html" key is required. The "href" key is optional.
sponsor: html: "<strong>Please sponsor us!</strong> Blah blah blah." href: https://paypal.example/foo-bar-baz
menu
A list of files to include in the navbar. If this key is missing, will be loaded from menu.yaml instead.
homepage
Hashref of options for the homepage (index.html). May contain keys "animation", "banner", "banner_fixation", "banner_position_x", and "banner_position_y".
The "animation" may be "waves1", "waves2", "swirl1", or "attract1". Each of these will create a pretty animation on the homepage. Some day I'll add support for more animations.
If "animation" is not defined, then "banner" can be used to supply the URL of a static image to use instead of an animation.
"banner_fixation" can be "scroll" or "fixed", and defaults to the latter. "banner_position_x" can be "left", "center", or "right". "banner_position_y" can be "top", "center", or "bottom". These each default to "center".
In the future, more homepage options may be available.
dist_dir
Directory for output. Defaults to a subdirectory called "docs".
root_url
URL for the output. Can be an absolute URL, but something like "/" is probably okay. (That's the default.)
codestyle
Name of a highlight.js theme, used for code syntax highlighting. Defaults to "github".
pod_filter
A list of section names which will be filtered out of pages generated from pod files. Uses "|" as a separator. Defaults to: "NAME|BUGS|AUTHOR|THANKS|COPYRIGHT AND LICENCE|DISCLAIMER OF WARRANTIES".
pod_titlecase
Boolean. Should ALL CAPS "=head1" headings from pod be converted to Title Case? Defaults to true.
pod_downgrade_headings
Converts pod "=head1" to <h2> tags in HTML, etc.
<h2>
The menu can be configured under the menu key of config.yaml, or in menu.yaml. This is a list of menu items. For example:
- name: installation title: Installation source: _pages/installation.md - name: hints title: Hints and Tips source: _pages/hints.pod - name: manual title: Manual children: - name: Foo-Bar pod: Foo::Bar - name: Foo-Bar-Baz pod: Foo::Bar::Baz
The name key is used for the output filename. ".html" is automatically appended.
The title key is the title of the document generated. It is used in the navbar and in the page's title element.
title
Each entry needs a source which is an input filename. The input may be pod or markdown. (At some future point, HTML input will also be supported.)
source
If the pod key is found, we'll find the pod via @INC, like perldoc does. This will helpfully also default title and name for you!
pod
@INC
A children key allows child pages to be listed. Only one level of nesting is supported in the navbar, but if further levels of nesting are used, these pages will still be built. (You'll just need to link to them manually somehow.)
children
A list item like this can be used to add dividers:
- divider: true
If the input is pod, you can also provide pod_filter, pod_titlecase, and pod_downgrade_headings settings which override the global settings.
If the input is markdown, you may use "----" (four hyphens) on a line by itself to divide the page into cute sections.
You'll need a file called _page/index.md for the site's homepage. The filename may be configurable some day.
You can create a file called custom.scss containing custom SCSS code to override or add to the defaults.
If you create a directory called images, this will be copied to docs/assets/images/ during the build process. This should be used for things like background images, etc.
Running make all will build the site.
make all
Running make clean will remove the docs directory and also any temporary SCSS files created during the build process.
make clean
docs
Example: https://github.com/exportertiny/exportertiny.github.io
Generated this site: https://exportertiny.github.io
Please report any bugs to https://github.com/tobyink/p5-web-perldistsite/issues.
Toby Inkster <tobyink@cpan.org>.
This software is copyright (c) 2023 by Toby Inkster.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
To install Web::PerlDistSite, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Web::PerlDistSite
CPAN shell
perl -MCPAN -e shell install Web::PerlDistSite
For more information on module installation, please visit the detailed CPAN module installation guide.