lib/App/Dapper/Init.pm

filter: Statementstmt 46.4% 46 / 99 Branchbran 0.0% 0 / 36 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 68.7% 11 / 16 Podpod 100% 4 / 4 totaltotal 39.3% 61 / 155 CC 21 SCAR 40.0
CC
21
Cov
34%
init
132.0
template_files
42.0
__ANON__
42.0
CRAP 54.8
« lib/App/Dapper/MCP.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 32 ▶use utf8;
Subroutine BEGIN: called CC=1 SCAR=0.0
52 32 ▶use 5.010;
Subroutine BEGIN: called CC=1 SCAR=0.0
53 32 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
54 32 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
55  
56 32 ▶use App::Dapper::Utils;
Subroutine BEGIN: called CC=1 SCAR=0.0
57 32 ▶use App::Dapper::Theme::Portfolio;
Subroutine BEGIN: called CC=1 SCAR=0.0
58 32 ▶use App::Dapper::Theme::Business;
Subroutine BEGIN: called CC=1 SCAR=0.0
59 32 ▶use App::Dapper::Theme::Docs;
Subroutine BEGIN: called CC=1 SCAR=0.0
60 32 ▶use File::Temp qw/ tempdir /;
Subroutine BEGIN: called CC=1 SCAR=0.0
61 32 ▶use File::Find ();
Subroutine BEGIN: called CC=1 SCAR=0.0
62 32 ▶use File::Basename ();
Subroutine BEGIN: called CC=1 SCAR=0.0
63  
64 32 my %TEMPLATES;
65  
66 $TEMPLATES{default} = {
67 32 '_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>
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 32 '_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 template: true
234 paginate:
235 category: blog
236 per_page: 10
237 ---
238 [% FOR post IN paginator.items %]
239 <article>
240 <h2><a href="[% post.url %]">[% post.title | html %]</a></h2>
241 <p class="meta">[% post.date.strftime('%d %B %Y') %]</p>
242 [% post.excerpt %]
243 <p><a href="[% post.url %]">Read more</a></p>
244 </article>
245 [% END %]
246  
247 <nav class="pages">
248 [% IF paginator.previous_url %]<a href="[% paginator.previous_url %]">Newer posts</a>[% END %]
249 [% IF paginator.next_url %]<a href="[% paginator.next_url %]">Older posts</a>[% END %]
250 </nav>
251 FILE
252  
253 '_source/about.md' => <<'FILE',
254 ---
255 title: About
256 description: Who writes this blog, and why.
257 ---
258  
259 This is the about page. Edit `_source/about.md` to tell readers who you are.
260  
261 FILE
262  
263 '_source/blog/_schema.yml' => <<'FILE',
264 # Every post must have these. Run "dapper check" to see any problems.
265 required: [title, date, categories]
266 fields:
267 title:
268 type: string
269 max_length: 100
270 date:
271 type: date
272 categories:
273 type: list
274 values: [blog]
275 tags:
276 type: list
277 description:
278 type: string
279 max_length: 200
280 FILE
281  
282 '_source/blog/welcome.md' => <<'FILE',
283 ---
284 title: Welcome to Your New Blog
285 layout: post
286 categories: blog
287 tags: [dapper]
288 date: 2026-01-01T09:00:00
289 description: What's in this starter blog, and where to go next.
290 ---
291  
292 This is your first post. The first paragraph of a post is its excerpt, shown
293 on the home page and in the feed.
294  
295 Posts live in `_source/blog/`. Each starts with front matter (the settings
296 between the `---` lines), and `_source/blog/_schema.yml` says which settings
297 every post needs.
298  
299 ## Code
300  
301 Code blocks are highlighted:
302  
303 ```perl
304 print "Hello, world!\n";
305 ```
306  
307 ## Next steps
308  
309 * Edit `_config.yml` with your site's name and address.
310 * Run `dapper serve` and open http://localhost:8000.
311 * Run `dapper check` to find broken links and missing settings.
312  
313 FILE
314  
315 '_source/blog/writing-posts.md' => <<'FILE',
316 ---
317 title: Writing Posts
318 layout: post
319 categories: blog
320 tags: [dapper, writing]
321 date: 2026-01-02T09:00:00
322 ---
323  
324 Create a file in `_source/blog/` with a title, a date and `categories: blog`,
325 then write in Markdown below the front matter. The post appears on the home
326 page, in the feed, on its tag pages and in the sitemap.
327  
328 FILE
329  
330 '_data/menu.yml' => <<'FILE',
331 # The links in the site's header (site.data.menu)
332 - label: Home
333 url: /
334 - label: Blog
335 url: /blog/
336 - label: About
337 url: /about.html
338 FILE
339  
340 'css/site.css' => <<'FILE',
341 body {
342 font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
343 line-height: 1.6;
344 max-width: 42em;
345 margin: 0 auto;
346 padding: 1em;
347 color: #222;
348 }
349 header { display: flex; justify-content: space-between; align-items: baseline; margin-bottom: 2em; }
350 header nav a { margin-left: 1em; }
351 .site-name { font-weight: bold; text-decoration: none; color: inherit; }
352 .meta { color: #666; font-size: 0.9em; }
353 pre { overflow-x: auto; }
354 footer { margin-top: 3em; color: #666; font-size: 0.9em; }
355 @media (prefers-color-scheme: dark) {
356 body { background: #111; color: #ddd; }
357 a { color: #8ab4f8; }
358 }
359 FILE
360 };
361  
362 # Notes about each template, added to AGENTS.md below the part Dapper writes
363 32 my %NOTES;
364  
365 32 my %DESCRIPTIONS = (
366 default => 'The smallest project: a project file, one layout and one page',
367 blog => 'A blog: paginated home page, posts, category and tag pages, feed, a schema for posts',
368 );
369  
370 32 for my $theme (qw/ Portfolio Business Docs /) {
371 96 my $class = "App::Dapper::Theme::$theme";
372 96 my $name = lc $theme;
373 96 $TEMPLATES{$name} = $class->files();
374 96 $DESCRIPTIONS{$name} = $class->description();
375 }
376  
377 32 my $GITIGNORE = <<'FILE';
378 _output/
379 .dapper/
380 FILE
381  
382 32 $NOTES{blog} = <<'NOTES';
383 ## About this blog
384  
385 - Posts go in `_source/blog/`, one Markdown file each, with `layout: post`,
386 `categories: blog`, a `title`, a `date` and optional `tags`.
387 - The home page (`_source/index.html`) lists posts ten to a page, newest first.
388 - The menu is `_data/menu.yml`.
389 NOTES
390 32 $NOTES{$_} = "App::Dapper::Theme::\u$_"->notes() for qw/ portfolio business docs /;
391  
392 =head2 templates
393  
394 Returns the names of the built-in templates.
395  
396 =cut
397  
398 0 ▶sub templates {
Subroutine templates: not called CC=1 SCAR=6.9
Pod documented
399 0 return sort keys %TEMPLATES;
400 }
401  
402 =head2 description
403  
404 Takes a template name and returns its one-line description.
405  
406 =cut
407  
408 0 ▶sub description {
Subroutine description: not called CC=1 SCAR=6.9
Pod documented
409 0 my ($name) = @_;
410 0 return $DESCRIPTIONS{$name};
411 }
412  
413 =head2 template_files
414  
415 Takes a template: a built-in name, a directory, or a git URL. Returns a hash
416 of the template's files (path to content) and its notes for C<AGENTS.md>.
417  
418 =cut
419  
420 0 ▶sub template_files {
Subroutine template_files: not called CC=6 SCAR=37.4
Pod documented
421 0 my ($template) = @_;
422  
423 0 ▶ return ($TEMPLATES{$template}, $NOTES{$template}) if $TEMPLATES{$template};
Branch: 1 branch
BranchTrueFalseTotal
if $TEMPLATES{$template} 0 0 0
424  
425 0 my $dir = $template;
426 0 ▶ if ($template =~ m{^(?:https?|git|ssh)://|^git@|\.git$}) {
Branch: 2 branches
BranchTrueFalseTotal
if ($template =~ m[^(?:https?|git|ssh)://|^git@|\.git$]) { } 0 0 0
elsif (not -d $dir) { } 0 0 0
427 0 $dir = tempdir(CLEANUP => 1) . '/template';
428 0 ▶ system('git', 'clone', '--quiet', '--depth', '1', '--', $template, $dir) == 0
Branch: 1 branch
BranchTrueFalseTotal
system("git", "clone", "--quiet", "--depth", 1, "--", $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
429 or die "error: could not clone the template from $template (is git installed, and is the URL right?)\n";
430 }
431 elsif (not -d $dir) {
432 0 die "error: there is no template called \"$template\"; use one of: " . join(', ', templates())
433 . ", a directory, or a git URL\n";
434 }
435  
436 0 my %files;
437 0 my $root = App::Dapper::Utils::name_bytes($dir);
438 File::Find::find({
439 no_chdir => 1,
440 0 ▶ wanted => sub {
Subroutine __ANON__: not called CC=6 SCAR=37.4
441 0 my $path = App::Dapper::Utils::name_chars($File::Find::name);
442 0 (my $relative = $path) =~ s{^\Q$dir\E/?}{};
443 0 ▶ return if $relative eq '';
Branch: 1 branch
BranchTrueFalseTotal
if $relative eq "" 0 0 0
444 0 ▶ if (-d $File::Find::name) {
Branch: 1 branch
BranchTrueFalseTotal
if (-d $File::Find::name) 0 0 0
445 0 ▶ $File::Find::prune = 1 if $relative =~ m{^(?:\.git|_output|\.dapper|node_modules)$};
Branch: 1 branch
BranchTrueFalseTotal
if $relative =~ /^(?:\.git|_output|\.dapper|node_modules)$/ 0 0 0
446 0 return;
447 }
448 0 ▶ return if $relative =~ m{(?:^|/)\.DS_Store$};
Branch: 1 branch
BranchTrueFalseTotal
if $relative =~ m[(?:^|/)\.DS_Store$] 0 0 0
449 0 ▶ 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" 0 0 0
450 0 local $/;
451 0 $files{$relative} = { raw => scalar <$fh> };
452 0 close $fh;
453 },
454 0 }, $root);
455  
456 0 ▶ die "error: the template $template has no files\n" unless %files;
Branch: 1 branch
BranchTrueFalseTotal
unless %files 0 0 0
457 0 return (\%files, undef);
458 }
459  
460 =head2 init
461  
462 Initialize a Dapper project from a template. Takes the source directory,
463 output directory, layout directory, config file name and template name
464 (default: C<default>). Nothing is written if any of the files already exist.
465 A C<.gitignore> for the output directory is added if there isn't one.
466 Returns the template's notes for C<AGENTS.md>, if it has any.
467  
468 =cut
469  
470 0 ▶sub init {
Subroutine init: not called CC=11 SCAR=48.8
Pod documented
471 0 my ($source, $output, $layout, $config, $template) = @_;
472  
473 0 ▶ $template = 'default' unless defined $template;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $template 0 0 0
474 0 my ($files, $notes) = template_files($template);
475  
476 # Map the template's paths onto the directories being used
477 0 my %targets;
478 0 for my $path (keys %$files) {
479 0 my $target = $path;
480 0 $target =~ s{^_source/}{$source/};
481 0 $target =~ s{^_layout/}{$layout/};
482 0 ▶ $target = $config if $target eq '_config.yml';
Branch: 1 branch
BranchTrueFalseTotal
if $target eq "_config.yml" 0 0 0
483 0 $targets{$target} = $files->{$path};
484 }
485  
486 0 my @existing = sort grep { -e $_ } keys %targets;
487 0 ▶ die "error: refusing to initialize, these files already exist: @existing\n" if @existing;
Branch: 1 branch
BranchTrueFalseTotal
if @existing 0 0 0
488  
489 0 for my $target (sort keys %targets) {
490 0 my $content = $targets{$target};
491 0 ▶ if (ref $content) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $content) { } 0 0 0
492 # A file from a template directory, copied byte for byte
493 0 ▶ print "Creating $target\n" unless $App::Dapper::Utils::QUIET;
Branch: 1 branch
BranchTrueFalseTotal
unless $App::Dapper::Utils::QUIET 0 0 0
494 0 my $dir = File::Basename::dirname($target);
495 0 ▶ App::Dapper::Utils::create_dir($dir) unless -d $dir;
Branch: 1 branch
BranchTrueFalseTotal
unless -d $dir 0 0 0
496 0 ▶ 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" 0 0 0
497 0 print $fh $content->{raw};
498 0 close $fh;
499 }
500 else {
501 0 App::Dapper::Utils::create_file($target, $content);
502 }
503 }
504  
505 0 ▶ if (not -e '.gitignore') {
Branch: 1 branch
BranchTrueFalseTotal
unless (-e ".gitignore") 0 0 0
506 0 (my $ignore = $GITIGNORE) =~ s{^_output/}{$output/}m;
507 0 App::Dapper::Utils::create_file('.gitignore', $ignore);
508 }
509  
510 0 return $notes;
511 }
512  
513 32 1;
« lib/App/Dapper/MCP.pm ↑ Summary lib/App/Dapper/Utils.pm »