all: allow combination of default and custom stylesheet

To combine default stylesheet with custom CSS, set the value to "default" and the file name of custom CSS, separated by comma. This is the recommended way to use custom stylesheet since it can be set only on specific pages. ---- // In asciidoctor: :stylesheet: default, custom.css // In markdown: stylesheet: default, custom.css ---- To disable default stylesheet and only using custom CSS, set the value only to the file name of custom CSS. Another way to use custom stylesheet is by creating your own template and pass it to `serve` or `convert` command. This method makes the stylesheet applied to all pages.
author: Shulhan <ms@kilabit.info> 2026-01-29 21:07:22 +0700
committer: Shulhan <ms@kilabit.info> 2026-02-02 16:40:16 +0700
commit: f578b0ba7341f8bc97d13cd165070002596cb106 (patch)
tree: 44771b43cdcd4e36f56ec6dda2d7b4baab75d71e
parent: 1af4644cb401e64ac20ecb7f12e898096470eb61 (diff)
download: ciigo-f578b0ba7341f8bc97d13cd165070002596cb106.tar.xz
4 files changed, 135 insertions, 13 deletions
diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc
index 3dc678f..e5d21fe 100644
--- a/CHANGELOG.adoc
+++ b/CHANGELOG.adoc
@@ -23,6 +23,53 @@ template, we need to restart the "ciigo serve" command.
 Using memfs make us easy to update and see the changes directly, without
 restarting the server.
 
+**🌼 all: improve the default stylesheet and template**
+
+Add common styles for asciidoctor elements with dark theme.
+Common styles including title, header, anchor, lists, table, and footer.
+
+The foreground color changes to conform with color-contrast
+ratio threshold, with score AAA. [1]
+
+Add ARIA role to each section of pages: banner for topbar,
+main for page, and contentinfo for footer.
+This is to make the webpage more robust and functional no matter
+what screen reader technology is used. [2]
+
+For touch devices, increase the line height on Table of Contents.
+This is to help users who may have difficulty in confidently targeting or
+operating small controls. [3]
+
+In the default template, instead of splitting the topbar into top-heading
+and menu, breaking it down by class item.
+
+[1]: https://dequeuniversity.com/rules/axe/4.11/color-contrast +
+[2]: https://dequeuniversity.com/rules/axe/4.11/landmark-one-main +
+[3]: https://dequeuniversity.com/rules/axe/4.11/target-size
+
+
+**🌱 all: allow combination of default and custom stylesheet**
+
+To combine default stylesheet with custom CSS, set the value to "default"
+and the file name of custom CSS, separated by comma.
+This is the recommended way to use custom stylesheet since it can be set
+only on specific pages.
+
+----
+// In asciidoctor:
+:stylesheet: default, custom.css
+
+// In markdown:
+stylesheet: default, custom.css
+----
+
+To disable default stylesheet and only using custom CSS, set the value only
+to the file name of custom CSS.
+
+Another way to use custom stylesheet is by creating your own template and
+pass it to `serve` or `convert` command.
+This method makes the stylesheet applied to all pages.
+
 
 [#v0_15_3]
 ==  ciigo v0.15.3 (2025-12-27)
diff --git a/README.md b/README.md
index 51765e6..fe87051 100644
--- a/README.md
+++ b/README.md
@@ -320,6 +320,64 @@ That's it, happy writing!
 
 <!--}}}-->
 
+## Custom Stylesheet
+
+When converting an asciidoc or markdown to HTML, `ciigo` by
+default embed their own stylesheet.
+This is to provide better user experiences when using the program for the
+first time.
+
+To turn it off in asciidoc document, set the `stylesheet` attribute with "!"
+suffix,
+
+```
+= Title
+:stylesheet!:
+```
+
+To turn it off in markdown document, set the value to `false`,
+
+```
+---
+stylesheet: false
+---
+# Title
+```
+
+To combine default stylesheet with custom CSS, set the value to "default"
+and the file name of custom CSS, separated by comma.
+This is the recommended way to use custom stylesheet since it can be set
+only on specific pages.
+
+```
+// In asciidoctor:
+:stylesheet: default, custom.css
+
+// In markdown:
+stylesheet: default, custom.css
+```
+
+To disable default stylesheet and only using custom CSS, set the value only
+to the file name of custom CSS.
+
+Another way to use custom stylesheet is by creating your own template and
+pass it to `serve` or `convert` command.
+This method makes the stylesheet applied to all pages.
+
+```
+<html>
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+{{- range $k, $v := .Metadata}}
+    <meta name="{{ $k }}" content="{{ $v }}" />
+{{- end }}
+    <title>{{.Title}}</title>
+    <link rel="stylesheet" href="/custom.css" />
+  </head>
+...
+```
+
 ## Links
 
 <!--{{{-->
diff --git a/filehtml.go b/filehtml.go
index 6e5a080..7731ec0 100644
--- a/filehtml.go
+++ b/filehtml.go
@@ -39,6 +39,10 @@ func (fhtml *fileHTML) unpackAdocMetadata(doc *asciidoctor.Document) {
 		k string
 		v string
 	)
+
+	// By default `:stylesheet:` is set in Attributes.
+	// If user remove it, by using `:stylesheet!:`, the key would not
+	// exist in the map.
 	var withStylesheet bool
 
 	fhtml.Title = doc.Title.String()
@@ -47,10 +51,14 @@ func (fhtml *fileHTML) unpackAdocMetadata(doc *asciidoctor.Document) {
 	for k, v = range doc.Attributes.Entry {
 		switch k {
 		case asciidoctor.DocAttrStylesheet:
-			if len(v) != 0 {
-				fhtml.Styles = append(fhtml.Styles, v)
-			} else {
-				withStylesheet = true
+			vals := strings.Split(v, ",")
+			for _, v = range vals {
+				v = strings.TrimSpace(v)
+				if v == `` || v == `default` {
+					withStylesheet = true
+				} else {
+					fhtml.Styles = append(fhtml.Styles, v)
+				}
 			}
 		case asciidoctor.DocAttrAuthorNames:
 			fhtml.Metadata[asciidoctor.DocAttrAuthor] = v
@@ -86,10 +94,20 @@ func (fhtml *fileHTML) unpackMarkdownMetadata(metadata map[string]any) {
 		key = strings.ToLower(key)
 		switch key {
 		case asciidoctor.DocAttrStylesheet:
-			if vstr == `false` {
-				withStylesheet = false
-			} else {
-				fhtml.Styles = append(fhtml.Styles, vstr)
+			vals := strings.Split(vstr, ",")
+			for _, v := range vals {
+				v = strings.TrimSpace(v)
+
+				switch v {
+				case ``:
+					// Skip it.
+				case `false`:
+					withStylesheet = false
+				case `default`:
+					// Use embedded stylesheet.
+				default:
+					fhtml.Styles = append(fhtml.Styles, vstr)
+				}
 			}
 		case metadataTitle:
 			fhtml.Title = vstr
@@ -105,12 +123,8 @@ func (fhtml *fileHTML) unpackMarkdownMetadata(metadata map[string]any) {
 func (fhtml *fileHTML) initCSS(withStylesheet bool) {
 	var logp = `initCSS`
 
-	if len(fhtml.Styles) != 0 {
-		// User defined their custom CSS throught ":stylesheet:"
-		return
-	}
 	if !withStylesheet {
-		// User unset the stylesheet throught ":stylesheet!".
+		// User explicitly unset the default stylesheet.
 		return
 	}
 	css, err := staticfs.Get(`/ciigo.css`)
diff --git a/testdata/watcher_test.txt b/testdata/watcher_test.txt
index 4e00e9c..579d6ec 100644
--- a/testdata/watcher_test.txt
+++ b/testdata/watcher_test.txt
@@ -129,6 +129,9 @@ keywords: ciigo,markdown
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <meta name="keywords" content="ciigo,markdown" />
     <title>A new title</title>
+    <style>
+body{}
+    </style>
     <link rel="stylesheet" href="/path/to/style.css" />
   </head>
   <body>
author	Shulhan <ms@kilabit.info>	2026-01-29 21:07:22 +0700
committer	Shulhan <ms@kilabit.info>	2026-02-02 16:40:16 +0700
commit	f578b0ba7341f8bc97d13cd165070002596cb106 (patch)
tree	44771b43cdcd4e36f56ec6dda2d7b4baab75d71e
parent	1af4644cb401e64ac20ecb7f12e898096470eb61 (diff)
download	ciigo-f578b0ba7341f8bc97d13cd165070002596cb106.tar.xz