From f578b0ba7341f8bc97d13cd165070002596cb106 Mon Sep 17 00:00:00 2001 From: Shulhan Date: Thu, 29 Jan 2026 21:07:22 +0700 Subject: 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. --- CHANGELOG.adoc | 47 ++++++++++++++++++++++++++++++++++++++ README.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++ filehtml.go | 40 +++++++++++++++++++++----------- testdata/watcher_test.txt | 3 +++ 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. + +``` + + + + +{{- range $k, $v := .Metadata}} + +{{- end }} + {{.Title}} + + +... +``` + ## 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 A new title + -- cgit v1.3