design: Add date to document, use md

design/4-summary-includes.adoc → design/2023-11-04-summary-includes.md

@@ -1,48 +1,46 @@
-= Distributed summary documents with Summary Includes
-2023-11-04
-:toc: preamble
+# Distributed summary documents with Summary Includes
 
-Abstract::
-  Proposes an extension to stitchmd's summary document format
-  to support including other partial summary documents.
-  This enables stitching together of the summary document
-  from fragments spread across files.
-Issue::
-  https://github.com/abhinav/stitchmd/issues/4[#4]
+**Issue**: [#4](https://github.com/abhinav/stitchmd/issues/4)
 
-== Background
+Proposes an extension to stitchmd’s summary document format
+to support including other partial summary documents.
+This enables stitching together of the summary document
+from fragments spread across files.
 
-With stitchmd, the layout of the output is specified in a *summary file*.
+## Background
+
+With stitchmd, the layout of the output is specified in a **summary file**.
 The summary file is a Markdown subset:
-it's valid Markdown, but very restricted about what's allowed.
+it’s valid Markdown, but very restricted about what’s allowed.
 Individual documents are referenced in an itemized list in the summary file.
 
 Three kinds of items are supported in the list:
 
-File reference::
+* **File reference**:
   References a Markdown file that should be included in the output
   at that position and nesting level.
-Group::
+* **Group**:
   Header under which other items are grouped,
   but does not represent another document.
-External link::
+* **External link**:
   Link to an external resource.
   These are produced verbatim in the output.
 
-.Kinds of items
-[,markdown,line-comment=#]
-----
-- [Introduction](intro.md) # <1>
-- Getting started # <2>
+**Kinds of items**
+
+```markdown
+- [Introduction](intro.md) # ①
+- Getting started # ②
   - [Installation](install.md)
   - [Usage](usage.md)
-- [Community](https://example.com/discussions) # <3>
-----
-<1> File reference
-<2> Group
-<3> External link
+- [Community](https://example.com/discussions) # ③
+```
 
-== Problem
+1. File reference
+2. Group
+3. External link
+
+## Problem
 
 The summary file format is a central place for the output layout.
 This presents two obvious problems:
@@ -53,57 +51,55 @@ This presents two obvious problems:
   the summary documents for both must duplicate those items
   instead of being able to re-use the shared fragment.
 
-== Design
+## Design
 
 As a solution, a new kind of summary list item will be added:
-*summary include*.
+**summary include**.
 A summary include is a request to load another summary file
 and nest its contents at the current position.
 
-=== Syntax
+### Syntax
 
 The syntax for a summary include item will reuse the Markdown image syntax.
 
-[,markdown]
-----
+```markdown
 ![title](file.md)
-----
+```
 
 The image syntax includes a general suggestion of embedding something
-in the current document so it's a good fit for this purpose.
+in the current document so it’s a good fit for this purpose.
 
-=== Example
+### Example
 
 With a summary document like the following:
 
-[,markdown]
-----
+```markdown
 - ![Using the web UI](web/SUMMARY.md)
 - ![Using the CLI](cli/SUMMARY.md)
-----
+```
 
 stitchmd will load the referenced summaries
 and treat the result equivalent to the following:
 
-[,markdown,line-comment=#]
-----
-- Using the web UI # <1>
-  - [Create an account](web/register.md) <2>
+```markdown
+- Using the web UI # ①
+  - [Create an account](web/register.md) # ②
   - [Submit a request](web/submit.md)
 - Using the CLI
   - [Authorize your terminal](cli/auth.md)
   - [Submit a JSON request](cli/json.md)
-----
-<1> Included summaries are nested under a group named after the link title.
-<2> Links to files referenced inside included summaries
+```
+
+1. Included summaries are nested under a group named after the link title.
+2. Links to files referenced inside included summaries
     are adjusted to be relative to the parent summary file.
 
-== Future work
+## Future work
 
 In the future, we may allow:
 
 * Including another summary file without showing its items in the TOC.
 * Body in the summary file below the item list to be reproduced verbatim.
 
 The two pieces combined would fully address the scenario
-originally imagined in https://github.com/abhinav/stitchmd/issues/4[#4].
+originally imagined in [#4](https://github.com/abhinav/stitchmd/issues/4).