feat: automatically assign section number (#37)

* feat: automatically assign section number

* docs: add comments

contrib/typst/book/lib.typ

@@ -118,7 +118,7 @@
 /// #chapter("chapter1.typ")["Chapter 1"]
 /// #chapter("chapter2.typ", section: "1.2")["Chapter 1.2"]
 /// ```
-#let chapter(link, title, section: none) = metadata((
+#let chapter(link, title, section: auto) = metadata((
     kind: "chapter",
     link: link,
     section: section,
@@ -133,8 +133,8 @@
 /// // other chapters
 /// #suffix-chapter("chapter-suf.typ")["Title of Suffix Chapter"]
 /// ```
-#let prefix-chapter(link, title) = chapter(link, title)
-#let suffix-chapter(link, title) = chapter(link, title)
+#let prefix-chapter(link, title) = chapter(link, title, section: none)
+#let suffix-chapter(link, title) = chapter(link, title, section: none)
 
 /// Represents a divider in the summary sidebar
 #let divider = metadata((
@@ -204,6 +204,63 @@
   none
 }
 
+/// Internal method to number sections
+/// meta: array of summary nodes
+/// base: array of section number
+#let _numbering-sections(meta, base: ()) = {
+  // incremental section counter used in loop
+  let cnt = 1
+  for c in meta {
+    // skip non-chapter nodes or nodes without section number
+    if c.at("kind") != "chapter" or c.at("section") == none {
+      (c, )
+      continue
+    }
+
+    // default incremental section
+    let idx = cnt
+    cnt += 1
+    let num = base + (idx, )
+    // c.insert("auto-section", num)
+
+    let user-specified = c.at("section")
+    // c.insert("raw-section", repr(user-specified))
+
+    // update section number if user specified it by str or array
+    if user-specified != none and user-specified != auto {
+
+      // update number
+      num = if type(user-specified) == str {
+        // e.g. "1.2.3" -> (1, 2, 3)
+        user-specified.split(".").map(int)
+      } else if type(user-specified) == array {
+        for n in user-specified {
+          assert(type(n) == int, message: "invalid type of section counter specified " + repr(user-specified) + ", want number in array")
+        }
+
+        // e.g. (1, 2, 3)
+        user-specified
+      } else {
+        panic("invalid type of manual section specified " + repr(user-specified) + ", want str or array")
+      }
+
+      // update cnt
+      cnt = num.last() + 1
+    } 
+
+    // update section number
+    let auto-num = num.map(str).join(".")
+    c.at("section") = auto-num
+
+    // update sub chapters
+    if "sub" in c {
+      c.sub = _numbering-sections(c.at("sub"), base: num)
+    }
+
+    (c, )
+  }
+}
+
 /// show template for a book file
 /// Example:
 /// ```typ
@@ -216,6 +273,7 @@
   locate(loc => {
     let data = query(<typst-book-raw-book-meta>, loc).at(0)
     let meta = _convert-summary(data)
+    meta.at("summary") = _numbering-sections(meta.at("summary"))
 
     book-meta-state.update(meta)
     [

github-pages/docs/book.typ

@@ -13,31 +13,31 @@
   summary: [ // begin of summary
     #prefix-chapter("introduction.typ")[Introduction]
     = User Guide
-    - #chapter("guide/installation.typ", section: "1")[Installation]
-    - #chapter("guide/get-started.typ", section: "2")[Get Started]
-    - #chapter("guide/faq.typ", section: "3")[Frequently Asked Questions]
-    - #chapter(none, section: "4")[Further reading]
+    - #chapter("guide/installation.typ")[Installation]
+    - #chapter("guide/get-started.typ")[Get Started]
+    - #chapter("guide/faq.typ")[Frequently Asked Questions]
+    - #chapter(none)[Further reading]
     = Reference Guide
-    - #chapter("cli/main.typ", section: "5")[Command Line Tool]
-      - #chapter("cli/init.typ", section: "5.1")[init]
-      - #chapter("cli/build.typ", section: "5.2")[build]
-      - #chapter("cli/serve.typ", section: "5.3")[serve]
-      - #chapter("cli/clean.typ", section: "5.4")[clean]
-      - #chapter("cli/completions.typ", section: "5.5")[completions]
-    - #chapter("format/main.typ", section: "6")[Format]
-      - #chapter("format/book.typ", section: "6.1")[book.typ]
-        - #chapter("format/book-meta.typ", section: "6.1.1")[Book Metadata]
-          - #chapter(none, section: "6.1.1.1")[Draft chapter]
-          // - #chapter(none, section: "6.1.1.2")[chapter with - markers]
-          // - #chapter(none, "= Introduction", section: "6.1.1.2")
-          // - #chapter(none, section: "6.1.1.2")[#text("= Introduction")]
-        - #chapter("format/build-meta.typ", section: "6.1.2")[Build Metadata]
-      - #chapter("format/theme.typ", section: "6.2")[Theme]
-      - #chapter(none, section: "6.3")[Typst Support]
-    - #chapter(none, section: "7")[For developers]
-      - #chapter(none, section: "7.1")[Typst-side APIs]
-      - #chapter(none, section: "7.2")[typst-book CLI Internals]
-      - #chapter(none, section: "7.3")[Alternative Backends]
+    - #chapter("cli/main.typ")[Command Line Tool]
+      - #chapter("cli/init.typ")[init]
+      - #chapter("cli/build.typ")[build]
+      - #chapter("cli/serve.typ")[serve]
+      - #chapter("cli/clean.typ")[clean]
+      - #chapter("cli/completions.typ")[completions]
+    - #chapter("format/main.typ")[Format]
+      - #chapter("format/book.typ")[book.typ]
+        - #chapter("format/book-meta.typ")[Book Metadata]
+          - #chapter(none)[Draft chapter]
+          // - #chapter(none)[chapter with - markers]
+          // - #chapter(none, "= Introduction")
+          // - #chapter(none)[#text("= Introduction")]
+        - #chapter("format/build-meta.typ")[Build Metadata]
+      - #chapter("format/theme.typ")[Theme]
+      - #chapter(none)[Typst Support]
+    - #chapter(none)[For developers]
+      - #chapter(none)[Typst-side APIs]
+      - #chapter(none)[typst-book CLI Internals]
+      - #chapter(none)[Alternative Backends]
   // end of summary
   ]
 )