diff options
| -rw-r--r-- | CHANGELOG.adoc | 47 | ||||
| -rw-r--r-- | README.md | 58 | ||||
| -rw-r--r-- | filehtml.go | 40 | ||||
| -rw-r--r-- | 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) @@ -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> |