lib/App/Dapper/Init.pm

filter: Statementstmt 97.0% 97 / 100 Branchbran 78.9% 30 / 38 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 16 / 16 Podpod 100% 4 / 4 totaltotal 93.0% 147 / 158 CC 22 SCAR 17.9
CC
22
Cov
92%
init
11.0
template_files
7.4
__ANON__
6.0
CRAP 6.0
« lib/App/Dapper/Collections.pm ↑ Summary lib/App/Dapper/Utils.pm »
1 package App::Dapper::Init;
2  
3 =head1 NAME
4  
5 App::Dapper::Init - Starter projects for the "dapper init" command.
6  
7 =head1 DESCRIPTION
8  
9 C<dapper init> writes a starter project into the current directory. These
10 templates are built in (C<dapper templates> lists them):
11  
12 =over 4
13  
14 =item B<default>
15  
16 The smallest project: a project file, one layout and one page.
17  
18 =item B<blog>
19  
20 A complete blog: a home page that lists the newest posts across several
21 pages, a page per post, category and tag pages, an Atom feed, a sitemap,
22 SEO tags, a schema for posts, a menu from a data file, code highlighting,
23 and optional search.
24  
25 =item B<portfolio>
26  
27 A grid of projects with images, and about and contact pages.
28  
29 =item B<business>
30  
31 A small business: services, opening hours, contact details and news, all from
32 one data file.
33  
34 =item B<docs>
35  
36 Documentation with a sidebar, previous and next links, and code highlighting.
37  
38 =back
39  
40 $ dapper init
41 $ dapper init --template blog
42 $ dapper init --template ./my-theme
43 $ dapper init --template https://github.com/someone/dapper-theme.git
44  
45 A template can also be a directory, or a git repository (cloned with C<git>),
46 laid out like a project: its files are copied into the current directory
47 (without C<.git>, the output directory or C<.dapper>).
48  
49 =cut
50  
51 190 ▶use utf8;
Subroutine BEGIN: called CC=1 SCAR=0.0
52 190 ▶use 5.010;
Subroutine BEGIN: called CC=1 SCAR=0.0
53 190 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
54 190 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
55  
56 190 ▶use App::Dapper::Utils;
Subroutine BEGIN: called CC=1 SCAR=0.0
57 190 ▶use App::Dapper::Theme::Portfolio;
Subroutine BEGIN: called CC=1 SCAR=0.0
58 190 ▶use App::Dapper::Theme::Business;
Subroutine BEGIN: called CC=1 SCAR=0.0
59 190 ▶use App::Dapper::Theme::Docs;
Subroutine BEGIN: called CC=1 SCAR=0.0
60 190 ▶use File::Temp qw/ tempdir /;
Subroutine BEGIN: called CC=1 SCAR=0.0
61 190 ▶use File::Find ();
Subroutine BEGIN: called CC=1 SCAR=0.0
62 190 ▶use File::Basename ();
Subroutine BEGIN: called CC=1 SCAR=0.0
63  
64 190 my %TEMPLATES;
65  
66 $TEMPLATES{default} = {
67 190 '_config.yml' => <<'FILE',
68 # Dapper configuration file
69 ---
70 name : My Site
71  
72 # Where "dapper deploy" publishes the site. Uncomment "deploy:" and one
73 # of the targets below. See "Deploying with dapper deploy" in the README.
74 #deploy:
75 # s3:
76 # bucket: example.com
77 # github_pages:
78 # branch: gh-pages
79 # command: rsync -av --delete _output/ me@example.com:/var/www/site/
80 FILE
81  
82 '_source/index.md' => <<'FILE',
83 ---
84 layout: index
85 title: Welcome
86 ---
87  
88 Hello world.
89  
90 FILE
91  
92 '_layout/index.html' => <<'FILE',
93 <!DOCTYPE html>
94 <html lang="en">
95 <head>
96 <meta charset="utf-8">
97 <title>[% page.title %]</title>
98 </head>
99  
100 <body>
101  
102 [% page.content %]
103  
104 </body>
105 </html>
106  
107 FILE
108 };
109  
110 $TEMPLATES{blog} = {
111 190 '_config.yml' => <<'FILE',
112 # Dapper configuration file. See https://github.com/markdbenson/dapper
113 ---
114 name: My Blog
115 description: Notes, ideas and things I've learned.
116 author: Your Name
117  
118 # The address the site will be published at, without a trailing slash.
119 # Needed for the sitemap, the feed and absolute links in llms.txt.
120 url: https://example.com
121  
122 # The time zone that dates in posts are written in.
123 timezone: America/Chicago
124  
125 # An Atom feed of the blog at /feed.xml.
126 feed:
127 category: blog
128 limit: 20
129  
130 # A page for each category and tag.
131 category_pages:
132 layout: list
133 tag_pages:
134 layout: list
135  
136 # Set to true to build a search index with Pagefind (https://pagefind.app).
137 search: false
138  
139 # Where "dapper deploy" publishes the site. Uncomment "deploy:" and one
140 # of the targets below. See "Deploying with dapper deploy" in the README.
141 #deploy:
142 # s3:
143 # bucket: example.com
144 # github_pages:
145 # branch: gh-pages
146 # command: rsync -av --delete _output/ me@example.com:/var/www/site/
147 FILE
148  
149 '_layout/index.html' => <<'FILE',
150 ---
151 description: The page wrapper used by every page (header with the menu, footer, SEO tags, code highlighting, search)
152 ---
153 <!DOCTYPE html>
154 <html lang="en">
155 <head>
156 <meta charset="utf-8">
157 <meta name="viewport" content="width=device-width, initial-scale=1">
158 <title>[% IF page.title %][% page.title | html %] - [% END %][% site.name | html %]</title>
159 [% page.seo %]
160 <link rel="stylesheet" href="/css/site.css">
161 <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/github.min.css">
162 [% IF site.search %]
163 <link rel="stylesheet" href="/pagefind/pagefind-ui.css">
164 [% END %]
165 </head>
166 <body>
167 <header>
168 <a class="site-name" href="/">[% site.name | html %]</a>
169 <nav>
170 [% FOR item IN site.data.menu %]
171 <a href="[% item.url %]">[% item.label | html %]</a>
172 [% END %]
173 </nav>
174 </header>
175 [% IF site.search %]
176 <div id="search"></div>
177 [% END %]
178 <main>
179 [% page.content %]
180 </main>
181 <footer>
182 &copy; [% site.time.year %] [% site.author | html %] &middot;
183 <a href="/feed.xml">Feed</a>
184 </footer>
185 <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>
186 <script>hljs.highlightAll();</script>
187 [% IF site.search %]
188 <script src="/pagefind/pagefind-ui.js"></script>
189 <script>new PagefindUI({ element: "#search", showSubResults: true });</script>
190 [% END %]
191 </body>
192 </html>
193 FILE
194  
195 '_layout/post.html' => <<'FILE',
196 ---
197 layout: index
198 description: A blog post, with its date and tags
199 ---
200 <article data-pagefind-body>
201 <h1>[% page.title | html %]</h1>
202 <p class="meta">
203 [% page.date.strftime('%d %B %Y') %]
204 [% IF page.tags %]
205 &middot;
206 [% FOR tag IN page.tags %]
207 <a href="[% site.tag_pages.item(tag) %]">#[% tag | html %]</a>
208 [% END %]
209 [% END %]
210 </p>
211 [% page.content %]
212 </article>
213 FILE
214  
215 '_layout/list.html' => <<'FILE',
216 ---
217 layout: index
218 description: A list of posts, used for the category and tag pages
219 ---
220 <h1>[% page.title | html %]</h1>
221 [% FOR post IN page.posts %]
222 <article>
223 <h2><a href="[% post.url %]">[% post.title | html %]</a></h2>
224 <p class="meta">[% post.date.strftime('%d %B %Y') %]</p>
225 [% post.excerpt %]
226 </article>
227 [% END %]
228 FILE
229  
230 '_source/index.html' => <<'FILE',
231 ---
232 title: Home
233 description: The newest posts on this blog.
234 template: true
235 paginate:
236 category: blog
237 per_page: 10
238 ---
239 [% FOR post IN paginator.items %]
240 <article>
241 <h2><a href="[% post.url %]">[% post.title | html %]</a></h2>
242 <p class="meta">[% post.date.strftime('%d %B %Y') %]</p>
243 [% post.excerpt %]
244 <p><a href="[% post.url %]">Read more</a></p>
245 </article>
246 [% END %]
247  
248 <nav class="pages">
249 [% IF paginator.previous_url %]<a href="[% paginator.previous_url %]">Newer posts</a>[% END %]
250 [% IF paginator.next_url %]<a href="[% paginator.next_url %]">Older posts</a>[% END %]
251 </nav>
252 FILE
253  
254 '_source/about.md' => <<'FILE',
255 ---
256 title: About
257 description: Who writes this blog, and why.
258 ---
259  
260 This is the about page. Edit `_source/about.md` to tell readers who you are.
261  
262 FILE
263  
264 '_source/blog/_schema.yml' => <<'FILE',
265 # Every post must have these. Run "dapper check" to see any problems.
266 required: [title, date, categories]
267 fields:
268 title:
269 type: string
270 max_length: 100
271 date:
272 type: date
273 categories:
274 type: list
275 values: [blog]
276 tags:
277 type: list
278 description:
279 type: string
280 max_length: 200
281 FILE
282  
283 '_source/blog/welcome.md' => <<'FILE',
284 ---
285 title: Welcome to Your New Blog
286 layout: post
287 categories: blog
288 tags: [dapper]
289 date: 2026-01-01T09:00:00
290 description: What's in this starter blog, and where to go next.
291 ---
292  
293 This is your first post. The first paragraph of a post is its excerpt, shown
294 on the home page and in the feed.
295  
296 Posts live in `_source/blog/`. Each starts with front matter (the settings
297 between the `---` lines), and `_source/blog/_schema.yml` says which settings
298 every post needs.
299  
300 ## Code
301  
302 Code blocks are highlighted:
303  
304 ```perl
305 print "Hello, world!\n";
306 ```
307  
308 ## Next steps
309  
310 * Edit `_config.yml` with your site's name and address.
311 * Run `dapper serve` and open http://localhost:8000.
312 * Run `dapper check` to find broken links and missing settings.
313  
314 FILE
315  
316 '_source/blog/writing-posts.md' => <<'FILE',
317 ---
318 title: Writing Posts
319 layout: post
320 categories: blog
321 tags: [dapper, writing]
322 date: 2026-01-02T09:00:00
323 ---
324  
325 Create a file in `_source/blog/` with a title, a date and `categories: blog`,
326 then write in Markdown below the front matter. The post appears on the home
327 page, in the feed, on its tag pages and in the sitemap.
328  
329 FILE
330  
331 '_data/menu.yml' => <<'FILE',
332 # The links in the site's header (site.data.menu)
333 - label: Home
334 url: /
335 - label: Blog
336 url: /blog/
337 - label: About
338 url: /about.html
339 FILE
340  
341 'css/site.css' => <<'FILE',
342 body {
343 font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
344 line-height: 1.6;
345 max-width: 42em;
346 margin: 0 auto;
347 padding: 1em;
348 color: #222;
349 }
350 header { display: flex; justify-content: space-between; align-items: baseline; margin-bottom: 2em; }
351 header nav a { margin-left: 1em; }
352 .site-name { font-weight: bold; text-decoration: none; color: inherit; }
353 .meta { color: #666; font-size: 0.9em; }
354 pre { overflow-x: auto; }
355 footer { margin-top: 3em; color: #666; font-size: 0.9em; }
356 @media (prefers-color-scheme: dark) {
357 body { background: #111; color: #ddd; }
358 a { color: #8ab4f8; }
359 }
360 FILE
361 };
362  
363 # Notes about each template, added to AGENTS.md below the part Dapper writes
364 190 my %NOTES;
365  
366 190 my %DESCRIPTIONS = (
367 default => 'The smallest project: a project file, one layout and one page',
368 blog => 'A blog: paginated home page, posts, category and tag pages, feed, a schema for posts',
369 );
370  
371 190 for my $theme (qw/ Portfolio Business Docs /) {
372 570 my $class = "App::Dapper::Theme::$theme";
373 570 my $name = lc $theme;
374 570 $TEMPLATES{$name} = $class->files();
375 570 $DESCRIPTIONS{$name} = $class->description();
376 }
377  
378 190 my $GITIGNORE = <<'FILE';
379 _output/
380 .dapper/
381 FILE
382  
383 190 $NOTES{blog} = <<'NOTES';
384 ## About this blog
385  
386 - Posts go in `_source/blog/`, one Markdown file each, with `layout: post`,
387 `categories: blog`, a `title`, a `date` and optional `tags`.
388 - The home page (`_source/index.html`) lists posts ten to a page, newest first.
389 - The menu is `_data/menu.yml`.
390 NOTES
391 190 $NOTES{$_} = "App::Dapper::Theme::\u$_"->notes() for qw/ portfolio business docs /;
392  
393 =head2 templates
394  
395 Returns the names of the built-in templates.
396  
397 =cut
398  
399 10 ▶sub templates {
Subroutine templates: called CC=1 SCAR=0.0
Pod documented
400 10 return sort keys %TEMPLATES;
401 }
402  
403 =head2 description
404  
405 Takes a template name and returns its one-line description.
406  
407 =cut
408  
409 29 ▶sub description {
Subroutine description: called CC=1 SCAR=0.0
Pod documented
410 29 my ($name) = @_;
411 29 return $DESCRIPTIONS{$name};
412 }
413  
414 =head2 template_files
415  
416 Takes a template: a built-in name, a directory, or a git URL. Returns a hash
417 of the template's files (path to content) and its notes for C<AGENTS.md>.
418  
419 =cut
420  
421 35 ▶sub template_files {
Subroutine template_files: called CC=7 SCAR=20.0
Pod documented
422 35 my ($template) = @_;
423  
424 35 ▶ return ($TEMPLATES{$template}, $NOTES{$template}) if $TEMPLATES{$template};
Branch: 1 branch
BranchTrueFalseTotal
if $TEMPLATES{$template} 27 8 35
425  
426 8 my $dir = $template;
427 8 ▶ if ($template =~ m{^(?:https?|git|ssh|file)://|^git@|\.git$}) {
Branch: 2 branches
BranchTrueFalseTotal
if ($template =~ m[^(?:https?|git|ssh|file)://|^git@|\.git$]) { } 0 8 8
elsif (not -d $dir) { } 2 6 8
428 0 $dir = tempdir(CLEANUP => 1) . '/template';
429 # A shallow clone of a local repository makes git warn, so clone those in full
430 0 ▶ my @depth = $template =~ m{^(?:https?|git|ssh)://|^git@} ? ('--depth', '1') : ();
Branch: 1 branch
BranchTrueFalseTotal
$template =~ m[^(?:https?|git|ssh)://|^git@] ? : 0 0 0
431 0 ▶ system('git', 'clone', '--quiet', @depth, '--', $template, $dir) == 0
Branch: 1 branch
BranchTrueFalseTotal
system("git", "clone", "--quiet", @depth, "--", $template, $dir) == 0 or die "error: could not clone the template from $template (is git installed, and is the URL right?)\n" 0 0 0
432 or die "error: could not clone the template from $template (is git installed, and is the URL right?)\n";
433 }
434 elsif (not -d $dir) {
435 2 die "error: there is no template called \"$template\"; use one of: " . join(', ', templates())
436 . ", a directory, or a git URL\n";
437 }
438  
439 6 my %files;
440 6 my $root = App::Dapper::Utils::name_bytes($dir);
441 File::Find::find({
442 no_chdir => 1,
443 96 ▶ wanted => sub {
Subroutine __ANON__: called CC=6 SCAR=17.9
444 96 my $path = App::Dapper::Utils::name_chars($File::Find::name);
445 96 (my $relative = $path) =~ s{^\Q$dir\E/?}{};
446 96 ▶ return if $relative eq '';
Branch: 1 branch
BranchTrueFalseTotal
if $relative eq "" 5 91 96
447 91 ▶ if (-d $File::Find::name) {
Branch: 1 branch
BranchTrueFalseTotal
if (-d $File::Find::name) 46 45 91
448 46 ▶ $File::Find::prune = 1 if $relative =~ m{^(?:\.git|_output|\.dapper|node_modules)$};
Branch: 1 branch
BranchTrueFalseTotal
if $relative =~ /^(?:\.git|_output|\.dapper|node_modules)$/ 17 29 46
449 46 return;
450 }
451 45 ▶ return if $relative =~ m{(?:^|/)\.DS_Store$};
Branch: 1 branch
BranchTrueFalseTotal
if $relative =~ m[(?:^|/)\.DS_Store$] 9 36 45
452 36 ▶ open(my $fh, '<:raw', $File::Find::name) or die "error: could not read $path: $!\n";
Branch: 1 branch
BranchTrueFalseTotal
open my $fh, "<:raw", $File::Find::name or die "error: could not read ${path}: $!\n" 36 0 36
453 36 local $/;
454 36 $files{$relative} = { raw => scalar <$fh> };
455 36 close $fh;
456 },
457 6 }, $root);
458  
459 6 ▶ die "error: the template $template has no files\n" unless %files;
Branch: 1 branch
BranchTrueFalseTotal
unless %files 2 4 6
460 4 return (\%files, undef);
461 }
462  
463 =head2 init
464  
465 Initialize a Dapper project from a template. Takes the source directory,
466 output directory, layout directory, config file name and template name
467 (default: C<default>). Nothing is written if any of the files already exist.
468 A C<.gitignore> for the output directory is added if there isn't one.
469 Returns the template's notes for C<AGENTS.md>, if it has any.
470  
471 =cut
472  
473 12 ▶sub init {
Subroutine init: called CC=11 SCAR=24.0
Pod documented
474 12 my ($source, $output, $layout, $config, $template) = @_;
475  
476 12 ▶ $template = 'default' unless defined $template;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $template 1 11 12
477 12 my ($files, $notes) = template_files($template);
478  
479 # Map the template's paths onto the directories being used
480 12 my %targets;
481 12 for my $path (keys %$files) {
482 70 my $target = $path;
483 70 $target =~ s{^_source/}{$source/};
484 70 $target =~ s{^_layout/}{$layout/};
485 70 ▶ $target = $config if $target eq '_config.yml';
Branch: 1 branch
BranchTrueFalseTotal
if $target eq "_config.yml" 12 58 70
486 70 $targets{$target} = $files->{$path};
487 }
488  
489 12 my @existing = sort grep { -e $_ } keys %targets;
490 12 ▶ die "error: refusing to initialize, these files already exist: @existing\n" if @existing;
Branch: 1 branch
BranchTrueFalseTotal
if @existing 4 8 12
491  
492 8 for my $target (sort keys %targets) {
493 44 my $content = $targets{$target};
494 44 ▶ if (ref $content) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $content) { } 9 35 44
495 # A file from a template directory, copied byte for byte
496 9 ▶ print "Creating $target\n" unless $App::Dapper::Utils::QUIET;
Branch: 1 branch
BranchTrueFalseTotal
unless $App::Dapper::Utils::QUIET 9 0 9
497 9 my $dir = File::Basename::dirname($target);
498 9 ▶ App::Dapper::Utils::create_dir($dir) unless -d $dir;
Branch: 1 branch
BranchTrueFalseTotal
unless -d $dir 4 5 9
499 9 ▶ open(my $fh, '>:raw', $target) or die "error: could not write $target: $!\n";
Branch: 1 branch
BranchTrueFalseTotal
open my $fh, ">:raw", $target or die "error: could not write ${target}: $!\n" 9 0 9
500 9 print $fh $content->{raw};
501 9 close $fh;
502 }
503 else {
504 35 App::Dapper::Utils::create_file($target, $content);
505 }
506 }
507  
508 7 ▶ if (not -e '.gitignore') {
Branch: 1 branch
BranchTrueFalseTotal
unless (-e ".gitignore") 5 2 7
509 5 (my $ignore = $GITIGNORE) =~ s{^_output/}{$output/}m;
510 5 App::Dapper::Utils::create_file('.gitignore', $ignore);
511 }
512  
513 7 return $notes;
514 }
515  
516 190 1;
« lib/App/Dapper/Collections.pm ↑ Summary lib/App/Dapper/Utils.pm »