Use inko-markdown compatible Markdown

Changelog: other

README.md

@@ -5,7 +5,7 @@ after [xkcd 148](https://xkcd.com/148/).
 
 ## Requirements
 
-- Inko 0.14.0 or newer
+- Inko 0.15.0 or newer
 
 ## Installation
 

src/wobsite.inko

@@ -410,12 +410,14 @@ class pub Site {
   #
   # Building a website that consists of simple text and CSS files:
   #
-  #     import wobsite (Site)
-  #
-  #     Site.build(fn (site) {
-  #       site.copy('*.txt')
-  #       site.copy('*.css')
-  #     })
+  # ```
+  # import wobsite (Site)
+  #
+  # Site.build(fn (site) {
+  #   site.copy('*.txt')
+  #   site.copy('*.css')
+  # })
+  # ```
   fn pub static build(func: fn (mut Site)) {
     let source = Path.new('source')
     let output = Path.new('public')
@@ -462,11 +464,13 @@ class pub Site {
   #
   # # Examples
   #
-  #     import wobsite (Site)
+  # ```
+  # import wobsite (Site)
   #
-  #     Site.build(fn (site) {
-  #       site.generate('feed.xml') fn (files) { 'Example content' }
-  #     })
+  # Site.build(fn (site) {
+  #   site.generate('feed.xml') fn (files) { 'Example content' }
+  # })
+  # ```
   fn pub mut generate(
     path: String,
     builder: uni fn (ref Files) -> Result[String, String],
@@ -483,9 +487,11 @@ class pub Site {
   #
   # # Examples
   #
-  #     import wobsite (Site)
+  # ```inko
+  # import wobsite (Site)
   #
-  #     Site.build(fn (site) { site.copy('*.css') })
+  # Site.build(fn (site) { site.copy('*.css') })
+  # ```
   fn pub mut copy(pattern: String) {
     @files.matching(pattern).each(fn (path) {
       @pending += 1

src/wobsite/markdown.inko

@@ -1,9 +1,23 @@
+# Processing of Markdown documents.
 import builder.html
 import markdown.html (Filter)
 import std.set (Set)
 import syntax (Languages)
 import syntax.format (Html)
 
+# A filter that applies syntax highlighting to a Markdown document.
+#
+# This filter processes fenced code blocks that are tagged with a language, such
+# as the following:
+#
+# ````markdown
+# ```inko
+# this_is_inko_code
+# ```
+# ````
+#
+# Syntax highlighting is performed using
+# [inko-syntax](https://github.com/yorickpeterse/inko-syntax).
 class pub SyntaxHighlight {
   let @languages: Languages
 
@@ -69,6 +83,24 @@ impl Filter for SyntaxHighlight {
   }
 }
 
+# A filter that adds support for admonitions (notes, warnings, etc).
+#
+# Admonitions use the custom block syntax of inko-markdown. For example, to
+# create a note you'de use the following syntax:
+#
+# ```markdown
+# ::: note
+# The body goes here.
+# :::
+# ```
+#
+# The following admonition types are supported:
+#
+# - discuss
+# - info
+# - note
+# - tip
+# - warn
 class pub Admonitions {
   # The admonition classes that are supported.
   let pub @types: Set[String]

src/wobsite/time.inko

@@ -1,3 +1,4 @@
+# Methods for parsing and formatting dates and times.
 import std.int
 import std.time (DateTime)
 
@@ -24,6 +25,22 @@ fn pad_zero(value: Int) -> String {
   value.to_string.pad_start('0', chars: 2)
 }
 
+# Parses a `DateTime` from a `String`.
+#
+# The expected format is `YYYY-MM-DDTHH:MM:SS`. The year, month, and day are
+# required, but the rest is optional.
+#
+# # Errors
+#
+# If the input is invalid, an `Option.None` is returned.
+#
+# # Examples
+#
+# ```inko
+# import wobsite.time (parse_date)
+#
+# parse_date('2024-01-02T13:14:15:Z') # => Option.Some(DateTime(year: 2024, month: 1, day: 2, hour: 13, minute: 14, second: 15, sub_second: 0.0, utc_offset: 0))
+# ```
 fn pub parse_date(string: String) -> Option[DateTime] {
   if string.size < 10 { return Option.None }
 
@@ -41,10 +58,52 @@ fn pub parse_date(string: String) -> Option[DateTime] {
   )
 }
 
+# Formats a `DateTime` in a human readable format.
+#
+# # Examples
+#
+# ```inko
+# import std.time (DateTime)
+# import wobsite.time (human_readable_date)
+#
+# let date = DateTime(
+#   year: 2024,
+#   month: 1,
+#   day: 2,
+#   hour: 13,
+#   minute: 14,
+#   second: 15,
+#   sub_second: 0.0,
+#   utc_offset: 0,
+# )
+#
+# human_readable_date(date) # => 'January 2, 2024'
+# ```
 fn pub human_readable_date(date: ref DateTime) -> String {
   '${MONTHS.get(date.month - 1)} ${date.day}, ${date.year}'
 }
 
+# Formats a `DateTime` as an ISO-8601 date.
+#
+# # Examples
+#
+# ```inko
+# import std.time (DateTime)
+# import wobsite.time (iso_date)
+#
+# let date = DateTime(
+#   year: 2024,
+#   month: 1,
+#   day: 2,
+#   hour: 13,
+#   minute: 14,
+#   second: 15,
+#   sub_second: 0.0,
+#   utc_offset: 0,
+# )
+#
+# iso_date(date) # => '2024-01-02T13:14:15Z'
+# ```
 fn pub iso_date(date: ref DateTime) -> String {
   '${date.year}-${pad_zero(date.month)}-${pad_zero(date.day)}T${pad_zero(date.hour)}:${pad_zero(date.minute)}:${pad_zero(date.second)}Z'
 }

src/wobsite/url.inko

@@ -1,3 +1,4 @@
+# Methods for working with URLs and URIs.
 import std.fs.path (Path)
 import wobsite (INDEX_FILE)