milestoner 18.4.0 → 18.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f42cba7a4f2b93a05d7fcf25fb973e2a241c8d1813a143baa779c2e1a310f1ed
-  data.tar.gz: 73635a67814d59b11bae524f45cb4878196aba7e302fa595ecedaaf89e350a6a
+  metadata.gz: acc8c51f0fa0cacdf7e8bc0e871a697520ce09c2b7af09c1dba01c1632b06671
+  data.tar.gz: 164ef1e821b63b7b382cbcb4dda7a9450c7d0493dfb92436b2161fcc983599f3
 SHA512:
-  metadata.gz: 9fcf5478cee6c0a63811cb133d27ae4bc292da15bacdbdb65f2edd29375057f87c23f15f4780ae68539439ed3c5c2011989477ea4c530b32effa5659f46735b1
-  data.tar.gz: a9e17509fa39de1247896518da061daa4586afbff8e905b5934728e5269e448ef973c1ffa1ac1136efd6d01a275912fe872c1fe84876c65c25dbaf7e32fed75a
+  metadata.gz: a999795a124cc155086e5826bd64880f9838d415e941b455cab6141bd66a05713e47009afbc11749809ff7692aced45bb13878f4a6fc0620ec520536f5741d0d
+  data.tar.gz: f2e01fb0744c54b2d1b6c87f7bd7932c71bde127a5509a101e05b37c87cc340371af596fd3bcf5edf72dfbcd25a99505a54925e323ed88a489af4672c7ebe3e2

data/README.adoc

@@ -3,6 +3,7 @@
 :figure-caption!:
 
 :ascii_doc_link: link:https://asciidoctor.org/docs/what-is-asciidoc[ASCII Doc]
+:ascii_doctor_link: link:https://asciidoctor.org[Asciidoctor]
 :cff_link: link:https://github.com/citation-file-format/ruby-cff[CFF]
 :etcher_link: link:https://alchemists.io/projects/etcher[Etcher]
 :firefox_link: link:https://www.mozilla.org/en-US/firefox[Firefox]
@@ -11,8 +12,8 @@
 :git_commit_anatomy_link: link:https://alchemists.io/articles/git_commit_anatomy[Git Commit Anatomy]
 :git_link: link:https://git-scm.com[Git]
 :git_lint_link: link:https://alchemists.io/projects/git-lint[Git Lint]
-:git_trailers_link: link:https://alchemists.io/articles/git_trailers[Git Trailers]
 :git_notes_link: link:https://alchemists.io/articles/git_notes[Git Notes]
+:git_trailers_link: link:https://alchemists.io/articles/git_trailers[Git Trailers]
 :hanami_link: link:https://hanamirb.org[Hanami]
 :hanami_views_link: link:https://alchemists.io/articles/hanami_views[Hanami Views]
 :hanamismith_link: link:https://alchemists.io/projects/hanamismith[Hanamismith]
@@ -21,12 +22,15 @@
 :markdown_link: link:https://daringfireball.net/projects/markdown[Markdown]
 :marked_link: link:https://marked2app.com[Marked 2]
 :net_news_wire_link: link:https://netnewswire.com[NetNewsWire]
+:redcarpet_link: link:https://github.com/vmg/redcarpet[Redcarpet]
+:rouge_link: link:https://rouge.jneen.net[Rouge]
 :ruby_link: link:https://www.ruby-lang.org[Ruby]
 :rubygems_link: link:https://rubygems.org[RubyGems]
 :rubysmith_link: link:https://alchemists.io/projects/rubysmith[Rubysmith]
 :runcom_link: link:https://alchemists.io/projects/runcom[Runcom]
+:sanitize_link: link:https://github.com/rgrove/sanitize[Sanitize]
 :strict_semantic_versioning_link: link:https://alchemists.io/articles/strict_semantic_versioning[Strict Semantic Versioning]
-:string_formats_link: link:https://ruby-doc.org/3.3.0/format_specifications_rdoc.html[String Formats]
+:string_formats_link: link:https://docs.ruby-lang.org/en/master/format_specifications_rdoc.html[String Formats]
 :syndication_link: link:https://alchemists.io/articles/syndication[Syndication]
 :versionaire_link: link:https://alchemists.io/projects/versionaire[Versionaire]
 :xdg_link: link:https://alchemists.io/projects/xdg[XDG]
@@ -50,43 +54,43 @@ toc::[]
 
 The following are screenshots of using this gem to render release notes for the {lode_link} gem. Even though {lode_link} is used for example purposes, keep in mind that Milestoner can be used for _any project and/or programming language_.
 
-=== ASCII Doc Format
+=== ASCII Doc
 
-image:https://alchemists.io/images/projects/milestoner/screenshots/build-ascii_doc-collapsed.png[Release Notes,width=1149,height=830,role=focal_point]
+image:https://alchemists.io/images/projects/milestoner/screenshots/build-ascii_doc-collapsed.png[Release Notes,width=1160,height=831,role=focal_point]
 
-image:https://alchemists.io/images/projects/milestoner/screenshots/build-ascii_doc-expanded.png[Release Notes,width=1149,height=1054,role=focal_point]
+image:https://alchemists.io/images/projects/milestoner/screenshots/build-ascii_doc-expanded.png[Release Notes,width=1160,height=1335,role=focal_point]
 
 * *Command*: `milestoner build --format ascii_doc`
 * *Renderer*: {ascii_doc_link}
 
-=== Feed Format
+=== Feed
 
-image:https://alchemists.io/images/projects/milestoner/screenshots/build-feed-collapsed.png[Release Notes,width=1109,height=1143,role=focal_point]
+image:https://alchemists.io/images/projects/milestoner/screenshots/build-feed-collapsed.png[Release Notes,width=1275,height=954,role=focal_point]
 
-image:https://alchemists.io/images/projects/milestoner/screenshots/build-feed-expanded.png[Release Notes,width=1109,height=1143,role=focal_point]
+image:https://alchemists.io/images/projects/milestoner/screenshots/build-feed-expanded.png[Release Notes,width=1275,height=1613,role=focal_point]
 
 * *Command*: `milestoner build --format feed`
 * *Renderer*: {net_news_wire_link}
 
 === Markdown Format
 
-image:https://alchemists.io/images/projects/milestoner/screenshots/build-markdown.png[Release Notes,width=789,height=718,role=focal_point]
+image:https://alchemists.io/images/projects/milestoner/screenshots/build-markdown.png[Release Notes,width=796,height=703,role=focal_point]
 
 * *Command*: `milestoner build --format markdown`
 * *Renderer*: {marked_link}
 
-=== Stream Format
+=== Stream
 
-image:https://alchemists.io/images/projects/milestoner/screenshots/build-stream.png[Release Notes,width=586,height=341,role=focal_point]
+image:https://alchemists.io/images/projects/milestoner/screenshots/build-stream.png[Release Notes,width=566,height=320,role=focal_point]
 
 * *Command*: `milestoner build --format stream`
 * *Renderer*: {iterm_link}
 
-=== Web Format
+=== Web
 
-image:https://alchemists.io/images/projects/milestoner/screenshots/build-web-collapsed.png[Release Notes,width=1195,height=878,role=focal_point]
+image:https://alchemists.io/images/projects/milestoner/screenshots/build-web-collapsed.png[Release Notes,width=1296,height=647,role=focal_point]
 
-image:https://alchemists.io/images/projects/milestoner/screenshots/build-web-expanded.png[Release Notes,width=1195,height=878,role=focal_point]
+image:https://alchemists.io/images/projects/milestoner/screenshots/build-web-expanded.png[Release Notes,width=1296,height=1032,role=focal_point]
 
 * *Command*: `milestoner build --format web`
 * *Renderer*: {firefox_link}
@@ -107,12 +111,12 @@ image:https://alchemists.io/images/projects/milestoner/screenshots/build-web-exp
 * Provides automatic versioning based on last {git_link} tag and {git_trailers_link}. See {git_commit_anatomy_link} for details.
 * Supports multiple build formats:
 ** {ascii_doc_link}
-** {syndication_link}
+** {syndication_link} (feed)
 ** {markdown_link}
 ** Stream (console)
-** link:https://html.spec.whatwg.org/multipage[Web]
+** link:https://html.spec.whatwg.org/multipage[Web] (HTML)
 * Supports {git_notes_link}.
-* Supports customization via your personal {xdg_link} and {hanami_views_link} configuration.
+* Supports customization via your personal {xdg_link}, {runcom_link}, and/or {hanami_views_link} configuration.
 
 == Requirements
 
@@ -273,7 +277,7 @@ The above can be customized as follows:
 *** `mime`: Required. The mime type. Defaults to HTML and XML.
 *** `relation`: Required. Identifies the relation of the link which can either be `self` (i.e. XML) or `alternate` (i.e. HTML).
 *** `uri`: Required. The link URI to follow for more information. Defaults to dynamic string formatting based on existing configuration values.
-* `tracker`: Required. Managed issue tracker details.
+* `tracker`: Required. Manages issue tracker details.
 ** `uri`: Required. The URI format for linking to issues as formatted using {string_formats_link}. Default: GitHub. The `id` is dynamically calculated via the commit `Issue` trailer as linted by {git_lint_link}. When no ID can be found, this will default to _All_ issues.
 
 As hinted at above, all URIs (including syndication), support {string_formats_link}. This means you can use the `%<key>s` format -- replacing `key` with the key of your choice -- to customize your configuration further.
@@ -292,39 +296,43 @@ image:https://alchemists.io/images/projects/milestoner/screenshots/usage-cache.p
 
 Milestoner's cache allows you to enrich user information (i.e. authors, collaborators, etc) by storing information in a `PStore` database as managed by the {lode_link} gem. Cache location, as with the Config, is managed by the {runcom_link} gem.
 
-User information should be sourced from whatever service you use for managing your source code. For example, when using GitHub, your workflow might look like this:
+User information should be sourced from whatever service used for managing your source code. For example, when using GitHub, your workflow might look like this:
 
 [source,bash]
 ----
 milestoner cache --list
-# 🟢 Listing users...
-# 🟢 No users found.
+# 🟢 [milestoner] Listing users...
+# 🟢 [milestoner] No users found.
 
 milestoner cache --create "111,jsmith,Jane Smith"
-# 🟢 Created: "Jane Smith"
+# 🟢 [milestoner] Created: "Jane Smith"
 
 milestoner cache --create "222,jdoe,John Doe"
-# 🟢 Created: "John Doe"
+# 🟢 [milestoner] Created: "John Doe"
 
 milestoner cache --create "333,jgrey,Jill Grey"
-# 🟢 Created: "Jill Grey"
+# 🟢 [milestoner] Created: "Jill Grey"
 
 milestoner cache --list
-# 🟢 Listing users...
-# 111, jsmith, Jane Smith
-# 222, jdoe, John Doe
-# 333, jgrey, Jill Grey
+# 🟢 [milestoner] Listing users...
+# External ID, Handle, Name
+# -------------------------
+# "111", "jsmith", "Jane Smith"
+# "222", "jdoe", "John Doe"
+# "333", "jgrey", "Jill Grey"
 
 milestoner cache --delete "Jill Grey"
-🟢 Deleted: "Jill Grey".
+# 🟢 [milestoner] Deleted: "Jill Grey".
 
 milestoner cache --list
-# 🟢 Listing users...
-# 111, jsmith, Jane Smith
-# 222, jdoe, John Doe
+# 🟢 [milestoner] Listing users...
+# External ID, Handle, Name
+# -------------------------
+# "111", "jsmith", "Jane Smith"
+# "222", "jdoe", "John Doe"
 
 milestoner cache --info
-# 🟢 Path: /Users/demo/.cache/milestoner/database.store.
+# 🟢 [milestoner] Path: /Users/bkuhlmann/.cache/milestoner/database.store.
 ----
 
 💡 Use `+https://api.github.com/users/<handle>+` to acquire the external ID for any GitHub user.
@@ -333,7 +341,7 @@ Once team member information is stored in your cache, you'll be able to build re
 
 If you don't use the cache, your release notes use a question mark (?) and _unknown_ for team members as highlighted below:
 
-image:https://alchemists.io/images/projects/milestoner/screenshots/no_cache.png[Usage,width=851,height=571,role=focal_point]
+image:https://alchemists.io/images/projects/milestoner/screenshots/no_cache.png[Usage,width=916,height=397,role=focal_point]
 
 === Build
 
@@ -344,8 +352,9 @@ The build command allows you to quickly build release notes to check the current
 [source,bash]
 ----
 milestoner build --format web
-# 🟢 Building milestone...
-# 🟢 Milestone built: /Users/bkuhlmann/Engineering/OSS/milestoner/tmp/milestone
+# 🟢 [milestoner] Building Milestoner (web)...
+# 🟢 [milestoner] Built: /Users/bkuhlmann/Engineering/OSS/milestoner/tmp/milestones/page.css.
+# 🟢 [milestoner] Built: /Users/bkuhlmann/Engineering/OSS/milestoner/tmp/milestones/index.html.
 ----
 
 The above command is so useful that I use the following `msw` (i.e. Milestoner Web) Bash alias to build current release notes or release notes for several tags:
@@ -357,22 +366,115 @@ The above command is so useful that I use the following `msw` (i.e. Milestoner W
 # Parameters: $1 (optional): Maximum tags to build. Default: 1.
 msw() {
   local max=${1:-1}
+  local root="tmp/milestones"
+  local path="$root/index.html"
 
   rm -rf tmp/milestones
 
   if [[ "$max" == 1 ]]; then
-    milestoner build --max "$max" --format web && open "tmp/milestones/index.html"
+    milestoner build --max "$max" --format web
+
+    if [[ -f "$path" ]]; then
+      open "$path"
+    fi
   else
     milestoner build --max "$max" --stylesheet "../page" --format web
-    ruby -run -e httpd "tmp/milestones" --port 3030 &
-    open "http://localhost:3030"
-    fg
+
+    if [[ -d "$root" ]]; then
+      ruby -run -e httpd "tmp/milestones" --port 3030 &
+      open "http://localhost:3030"
+      fg
+    fi
   fi
 }
 ----
 
 Check out the help documentation (i.e. `milestoner build --help`) for addition usage that explains what command line options you can use to overwrite the current configuration.
 
+==== Commits
+
+By default, all {git_link} commit messages support {ascii_doc_link} syntax but you can use {markdown_link} too.
+
+{ascii_doc_link} is rendered using the {ascii_doctor_link} gem while {markdown_link} is rendered using the {redcarpet_link} gem. Regardless of what renderer you choose, each supports syntax highlighting via the {rouge_link} gem. This also means you can customize the {rouge_link} styles via the `page.css` template as documented in the xref:_templates[Templates] section below.
+
+ℹ️ The {rouge_link} CSS classes are slightly cryptic in terms of readability but you can see how they are applied when inspecting the HTML DOM.
+
+Here's a couple examples of commit messages using {ascii_doc_link} and {markdown_link} syntax:
+
+*ASCII Doc*
+
+image:https://alchemists.io/images/projects/milestoner/screenshots/syntax-ascii_doc.png[ASCII Doc,width=950,height=763,role=focal_point]
+
+*Markdown*
+
+image:https://alchemists.io/images/projects/milestoner/screenshots/syntax-markdown.png[Markdown,width=933,height=921,role=focal_point]
+
+💡 To see an example of what this renders to HTML as, see the xref:_formats[Formats] section below.
+
+==== Sanitization
+
+Sanitization of commit messages is handled by the {sanitize_link} gem. This means you can only use a limited set of HTML elements (this includes {ascii_doc_link} and {markdown_link} rendering). Here's what's allowed:
+
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/b[b]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/em[em]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/i[i]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/strong[strong]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/u[u]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a[a]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/abbr[abbr]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/blockquote[blockquote]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/br[br]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/cite[cite]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/code[code]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dd[dd]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dfn[dfn]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl[dl]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dt[dt]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/kbd[kbd]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/li[li]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/mark[mark]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ol[ol]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/p[p]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/pre[pre]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/q[q]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/s[s]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/samp[samp]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/small[small]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/strike[strike]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sub[sub]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sup[sup]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/time[time]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ul[ul]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/var[var]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/audio[audio]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details[details]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img[img]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/source[source]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span[span]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary[summary]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video[video]
+
+The following global attributes are allowed for all elements:
+
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id[id]
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/class[class]
+
+The following attributes are limited to only a few elements like `a`, `abbr`, and `dfn` for the most part.
+
+* link:https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title[title]
+
+An additional set of attributes are allowed but are specific to each element and fairly limited. Ultimately, if you don't see an attribute being rendered then it's not allowed.
+
+==== Trailers
+
+Multiple {git_trailers_link} for your commits are supported which are detailed in the linked article. At a minimum, the `Milestone` trailer is highly recommended since this is how Milestoner handles xref:_automatic_versioning[Automatic Versioning] for you.
+
+One of the more powerful features of using {git_trailers_link} in your commit messages is they give you the ability to fully resolve what is defined in your default global xref:_customization[configuration]. Here's a more detailed breakdown:
+
+* *Format* (optional): Use `ascii_doc` or `markdown` for the value to control what syntax used to render your commit message. The default is `ascii_doc` but if your configuration uses a different default you can override that per commit message if desired.
+* *Issue* (optional): When supplied, Milestoner will automatically associate your commit with the corresponding issue ID you provide as a value. This works in conjunction with your xref:_customization[configuration].
+* *Milestone* (optional): This is detailed in the xref:_automatic_versioning[Automatic Versioning] section below.
+
 ==== Automatic Versioning
 
 As mentioned earlier, the calculation of version information happens automatically based on your last {git_link} tag and any {git_link} commit trailer metadata used. If none of this information is present, then the default version of `0.0.0` is used instead. All of this information is available to you via the following command:
@@ -436,7 +538,7 @@ Given the above, the resulting version would be: 2.0.0. This is because the high
 
 ==== Templates
 
-Build template functionality is powered by {hanami_views_link} which means you can completely customize _all_ build formats, templates, partials, stylesheets, images, and so much more.
+Template functionality is powered by {hanami_views_link} which means you can completely customize _all_ build formats, templates, partials, stylesheets, images, and much more.
 The quickest way to start customization is to copy the `templates` folder structure -- included with this gem -- to your preferred {runcom_link} configuration (i.e. global or local). For example, this gem's template structure is:
 
 ....
@@ -457,19 +559,34 @@ lib/milestoner/templates
 │  ├── _commit.md.erb
 │  ├── _commit.stream.erb
 │  ├── _commit.xml.erb
-│  ├── _icon.adoc.erb
-│  ├── _icon.html.erb
-│  ├── _icon.md.erb
-│  ├── _icon.xml.erb
+│  ├── _content.adoc.erb
+│  ├── _content.html.erb
+│  ├── _content.xml.erb
+│  ├── _logo.adoc.erb
+│  ├── _logo.html.erb
+│  ├── _logo.md.erb
+│  ├── _logo.xml.erb
+│  ├── _none.adoc.erb
+│  ├── _none.html.erb
+│  ├── _none.xml.erb
 │  ├── _profile.adoc.erb
 │  ├── _profile.html.erb
 │  ├── _profile.md.erb
 │  ├── _profile.xml.erb
+│  ├── _tag-insecure.html.erb
+│  ├── _tag-secure.html.erb
 │  ├── _tag.adoc.erb
 │  ├── _tag.html.erb
 │  ├── _tag.md.erb
 │  ├── _tag.stream.erb
 │  ├── _tag.xml.erb
+│  ├── _user.adoc.erb
+│  ├── _user.html.erb
+│  ├── _user.md.erb
+│  ├── _user.xml.erb
+│  ├── _users.adoc.erb
+│  ├── _users.html.erb
+│  ├── _users.xml.erb
 │  ├── show.adoc.erb
 │  ├── show.html.erb
 │  ├── show.md.erb
@@ -492,25 +609,29 @@ Milestoner searches your {runcom_link} configuration first and, if templates are
 
 Of all build formats supported, the web format is the most powerful and feature rich. The following showcases _some_ of the information rendered in this format based on commit activity.
 
-*With Basic Git Commit*
+*Overview*
 
-image:https://alchemists.io/images/projects/milestoner/screenshots/web_format-overview.png[Overview,width=1119,height=910,role=focal_point]
+image:https://alchemists.io/images/projects/milestoner/screenshots/web_format-overview.png[ASCII Doc,width=1157,height=843,role=focal_point]
 
-*With Collaborators and Signers*
+*With Valid Commit Signature*
 
-image:https://alchemists.io/images/projects/milestoner/screenshots/web_format-collaborators_and_signers.png[Collaborators and Signers,width=1118,height=1003,role=focal_point]
+image:https://alchemists.io/images/projects/milestoner/screenshots/web_format-commit_valid.png[ASCII Doc,width=1235,height=950,role=focal_point]
 
-*With Invalid Tag*
+*With Invalid Commit Signature*
 
-image:https://alchemists.io/images/projects/milestoner/screenshots/web_format-tag_invalid.png[Invalid Tag,width=1119,height=910,role=focal_point]
+image:https://alchemists.io/images/projects/milestoner/screenshots/web_format-commit_invalid.png[ASCII Doc,width=1235,height=950,role=focal_point]
 
 *With Valid Tag*
 
-image:https://alchemists.io/images/projects/milestoner/screenshots/web_format-tag_valid.png[Valid Tag,width=1119,height=910,role=focal_point]
+image:https://alchemists.io/images/projects/milestoner/screenshots/web_format-tag_valid.png[ASCII Doc,width=1089,height=1084,role=focal_point]
+
+*With Invalid Tag*
+
+image:https://alchemists.io/images/projects/milestoner/screenshots/web_format-tag_invalid.png[ASCII Doc,width=978,height=571,role=focal_point]
 
-*With Notes*
+*With ASCII Doc/Markdown*
 
-image:https://alchemists.io/images/projects/milestoner/screenshots/web_format-notes.png[Notes,width=1119,height=910,role=focal_point]
+image:https://alchemists.io/images/projects/milestoner/screenshots/web_format-ascii_doc.png[ASCII Doc,width=908,height=1938,role=focal_point]
 
 💡 See {git_notes_link} to learn more.
 

data/lib/milestoner/builders/feed.rb

@@ -8,7 +8,6 @@ module Milestoner
     # Builds syndicated feed output.
     class Feed
       include Milestoner::Import[:settings, :logger]
-      include Dry::Monads[:result]
 
       using Refinements::Pathname
 

data/lib/milestoner/builders/web.rb

@@ -17,9 +17,6 @@ module Milestoner
       end
 
       def call
-        settings.build_root.make_path
-        copy_stylesheet
-
         tagger.call
               .fmap { |tags| build tags }
               .alt_map { |message| failure message }
@@ -30,10 +27,14 @@ module Milestoner
       attr_reader :tagger, :view
 
       def build tags
+        make_root
+        copy_stylesheet
         tags.each { |tag| write tag }
         settings.build_root
       end
 
+      def make_root = settings.build_root.make_path
+
       def copy_stylesheet
         return unless settings.build_stylesheet
 

data/lib/milestoner/cli/actions/cache/create.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "core"
 require "sod"
 
 module Milestoner
@@ -17,17 +18,22 @@ module Milestoner
           on %w[-c --create], argument: "external_id,handle,name"
 
           def call values
-            process(values).bind { |user| log_info "Created: #{user.name.inspect}" }
+            case values.split ","
+              in String => external_id, String => handle, String => name
+                client.write(:users) { upsert({external_id:, handle:, name:}) }
+                      .bind { |user| log_info "Created: #{user.name.inspect}" }
+              in String, String then log_error "Name must be supplied."
+              in [String] then log_error "Handle and Name must be supplied."
+              in Core::EMPTY_ARRAY then log_error "No values given."
+              else log_error "Too many values given."
+            end
           end
 
           private
 
-          def process values
-            external_id, handle, name = values.split ","
-            client.write(:users) { upsert({external_id:, handle:, name:}) }
-          end
-
           def log_info(message) = logger.info { message }
+
+          def log_error(message) = logger.error { message }
         end
       end
     end

data/lib/milestoner/cli/actions/cache/list.rb

@@ -24,7 +24,15 @@ module Milestoner
           def print users
             return logger.info { "No users found." } if users.empty?
 
-            users.each { |user| io.puts user.to_h.values.join ", " }
+            header
+            users.each { |user| io.puts user.to_h.values.map(&:inspect).join ", " }
+          end
+
+          def header
+            header = "External ID, Handle, Name"
+
+            io.puts header
+            io.puts "-" * header.size
           end
         end
       end

data/lib/milestoner/commits/tagger.rb

@@ -24,15 +24,17 @@ module Milestoner
       end
 
       def call
-        git.tags("--sort=taggerdate")
-           .fmap { |tags| tail tags.last(settings.build_max).map(&:version) }
-           .fmap { |references| slice(references).reverse }
+        collect.fmap { |tags| tail tags.last(settings.build_max).map(&:version) }
+               .fmap { |references| slice(references).reverse }
+               .bind { |tags| tags.empty? ? Failure("No tags or commits.") : Success(tags) }
       end
 
       private
 
       attr_reader :enricher, :model
 
+      def collect = git.tagged? ? git.tags("--sort=taggerdate") : placeholder_with_commits
+
       def tail references
         references.append "HEAD" if settings.build_tail == "head"
         references
@@ -68,6 +70,21 @@ module Milestoner
         ]
       end
 
+      def placeholder_with_commits = enricher.call.fmap { |commits| placeholder_for commits }
+
+      def placeholder_for commits
+        return commits if commits.empty?
+
+        [
+          model[
+            author: commits.last.author,
+            commits:,
+            committed_at: Time.now,
+            version: settings.project_version
+          ]
+        ]
+      end
+
       def author tag
         author_enricher.call tag.with(author_name: tag.author_name || settings.project_author)
       end

data/lib/milestoner/renderers/asciidoc.rb

@@ -6,15 +6,24 @@ module Milestoner
   module Renderers
     # Renders ASCII Doc as HTML.
     class Asciidoc
-      def initialize client: Asciidoctor
+      SETTINGS = {
+        safe: :safe,
+        attributes: {
+          "source-highlighter" => "rouge",
+          "rouge-linenums-mode" => "inline"
+        }
+      }.freeze
+
+      def initialize settings: SETTINGS, client: Asciidoctor
+        @settings = settings
         @client = client
       end
 
-      def call(content) = client.convert content
+      def call(content) = client.convert content, settings
 
       private
 
-      attr_reader :client
+      attr_reader :settings, :client
     end
   end
 end

data/lib/milestoner/renderers/markdown.rb

@@ -1,12 +1,25 @@
 # frozen_string_literal: true
 
 require "redcarpet"
+require "rouge"
+require "rouge/plugins/redcarpet"
 
 module Milestoner
   module Renderers
     # Renders Markdown as HTML.
     class Markdown
-      def initialize client: Redcarpet::Markdown.new(Redcarpet::Render::HTML.new)
+      CLIENT = Redcarpet::Markdown.new Class.new(Redcarpet::Render::HTML)
+                                            .include(Rouge::Plugins::Redcarpet)
+                                            .set_temporary_name("redcarpet_html_rouge")
+                                            .new,
+                                       disable_indented_code_blocks: true,
+                                       fenced_code_blocks: true,
+                                       footnotes: true,
+                                       highlight: true,
+                                       superscript: true,
+                                       tables: true
+
+      def initialize client: CLIENT
         @client = client
       end
 

data/lib/milestoner/sanitizer.rb

@@ -19,13 +19,22 @@ module Milestoner
 
     attr_reader :defaults, :client
 
-    def configuration
-      client::Config.merge defaults,
-                           elements: defaults[:elements].including("img", "video"),
-                           attributes: defaults[:attributes].merge(
-                             "img" => %w[alt class height id loading src width],
-                             "video" => %w[class controls height id poster src width]
-                           )
+    def configuration = client::Config.merge(defaults, elements:, attributes:)
+
+    def elements
+      defaults[:elements].including "audio", "details", "img", "source", "span", "summary", "video"
+    end
+
+    def attributes
+      defaults[:attributes].merge(
+        all: %w[class id],
+        "a" => %w[href title],
+        "audio" => %w[autoplay controls controlslist crossorigin loop muted preload src],
+        "details" => %w[name open],
+        "img" => %w[alt height loading src width],
+        "source" => %w[type src srcset sizes media height width],
+        "video" => %w[controls height poster src width]
+      )
     end
   end
 end

data/lib/milestoner/syndication/builder.rb

@@ -21,7 +21,7 @@ module Milestoner
       end
 
       def call tags
-        return Failure "No content." if tags.empty?
+        return Failure "No tags or commits." if tags.empty?
 
         Success build_feed(tags).to_s
       rescue NoMethodError, RSS::Error => error

data/lib/milestoner/templates/milestones/_avatar.adoc.erb

@@ -1 +1 @@
-<% if name %>image:<%= url %>[<%= name %>,24,24]<% else %><%= render :icon, name: "missing", alt: "Unknown" %><% end %>
+image:<%= user.avatar_url %>[<%= user.image_alt %>,24,24]