Welcome to Rouge!

Finally, now we can also use Rouge for syntax highlighting (closes #107). - Add new `_assets/rouge/` folder: - `alan3.rb` -- our custom ALAN lexer. - `custom-rouge-adapter.rb` -- custom Asciidoctor adapter for Rouge. - `docinfo.html` -- custom CSS for Rouge highlighted docs. - Update the Sass toolchain to produce a `docinfo.html` file for Rouge in `_assets/rouge/. - Alan Design Docs: tweak their build script, now all documents are highlighted via Rouge.
alan-if · Jul 30, 2021 · 122687c · 122687c
1 parent d7f2ef5
commit 122687c
Show file tree

Hide file tree

Showing 13 changed files with 1,144 additions and 37 deletions.
diff --git a/_assets-src/sass/_rouge-template-alan.scss b/_assets-src/sass/_rouge-template-alan.scss
@@ -0,0 +1,204 @@
+// *****************************************************************************
+// *                                                                           *
+// *                 Rouge Alan Theme Template for Asciidoctor                 *
+// *                                                                           *
+// *****************************************************************************
+// A reusable variables-based '@import' template to quickly define Rouge themes
+// for Alan code in Asciidoctor. It can create both generic themes as well as
+// themes targetting a specific role/class, via the $ALAN-Role variable.
+
+// =============================================================================
+// Default Values
+// =============================================================================
+// Let's define some defaults for the template variables, so users don't have to
+// define every single variable.
+
+$ALAN-Border-radius:  4px !default;
+$ALAN-Border-width:   1px !default;
+$ALAN-Font-family:    inherit  !default;
+$ALAN-Font-size:      inherit !default;
+
+// Default Scheme: Use Alan scheme defined in "_color-scheme.scss"
+
+$ALAN-Background:      $GH-Whitish !default;
+$ALAN-Normal-Text:     $GH-Blackish !default;
+$ALAN-IDs:             $GH-Blackish !default;
+$ALAN-Numbers:         $GH-Blackish !default;
+$ALAN-Operators:       $GH-Blackish !default;
+$ALAN-Comments:        $GH-Grey !default;
+$ALAN-LineNumbers:     $GH-Grey !default;    // UNTESTED (need better colour?)
+$ALAN-Keywords:        $GH-DarkRed !default;
+$ALAN-Punctuation:     $GH-DarkRed !default;
+$ALAN-Builtin-Classes: $GH-DarkBlu !default;
+$ALAN-Hero:            $GH-DarkBlu !default;
+$ALAN-String:          $GH-Green !default;
+$ALAN-StrDelimiter:    $GH-Green !default;
+$ALAN-Escapes:         $GH-Orange !default;  // $p $n $i $t $a $l $v $$
+$ALAN-Interpolations:  $GH-Fuchsia !default; // $<n> $+<n> $0<n> $-<n> $!<n> $o
+
+// Context Vars:
+$ALAN-Hover:           #A09F93 !default;
+$ALAN-Border-Color:    $GH-Whitish !default;
+$ALAN-Callouts-BG:     black !default;
+$ALAN-Callouts-FG:     white !default;
+
+// -----------------
+// Highlight Markers
+// -----------------
+// Yellow Marker (for <mark> tag):
+$ALAN-MarkerYellow1: #CCFF00 !default; // Gradient left
+$ALAN-MarkerYellow2: #F5FF87 !default; // Gradient right
+
+// Green Marker (for <span class="green"> tag):
+$ALAN-MarkerGreen1: #A3FF8A !default; // Gradient left
+$ALAN-MarkerGreen2: rgba($ALAN-MarkerGreen1, .5) !default; // Gradient right
+
+// -----------------------------------------------------------------------------
+// Optional Language Settings
+// -----------------------------------------------------------------------------
+// If $ALAN-Role is set, the output theme will target that language, otherwise it
+// will be a generic theme for Highlight.
+
+$ALAN-Role: null    !default;
+$ref_role:  null;
+
+@if $ALAN-Role != null {
+  $ref_role:  ".#{$ALAN-Role}"   !global;
+}
+
+// =============================================================================
+// Theme Definition
+// =============================================================================
+
+// Language name shown when hovering:
+.listingblock#{$ref_role} code[data-lang=alan]::before{
+  color: $ALAN-Hover;
+}
+// Highlight Theme:
+.listingblock#{$ref_role} pre[class~=rouge][lang=alan] {
+  background-color: $ALAN-Background;
+  border-radius: $ALAN-Border-radius;
+  border: $ALAN-Border-width solid $ALAN-Border-Color;
+  &>code {
+    color: $ALAN-Normal-Text;
+    font-family: $ALAN-Font-family;
+    font-size: $ALAN-Font-size;
+    &>span {
+      font-style: normal;
+      font-weight: normal;
+      // AsciiDoc Callouts
+      &>.conum[data-value] {
+        background: $ALAN-Callouts-BG !important;
+        color: $ALAN-Callouts-FG !important;
+      }
+      &.m {
+        // Numbers -> Literal::Number
+        color: $ALAN-Numbers;
+      }
+      &.lin { // TBD!
+        // Line numbers
+        color: $ALAN-LineNumbers;
+      }
+      &.n {
+        // Identifiers -> Name
+        // -----------
+        color: $ALAN-IDs;
+      }
+      &.o {
+        // Operators -> Operator
+        // ---------
+        color: $ALAN-Operators;
+      }
+      &.p {
+        // Punctuation -> Punctuation
+        // -----------
+        color: $ALAN-Punctuation;
+      }
+      // -------------
+      //    Strings
+      // -------------
+      &.dl {
+        // String delimiter -> Str::Double::Delimiter
+        // ----------------
+        color: $ALAN-StrDelimiter;
+      }
+      &.s2 {
+        // String contents -> Str::Double
+        // ---------------
+        color: $ALAN-String;
+      }
+      &.s1 {
+        // Files String -> Str::Single
+        // ------------
+        color: $ALAN-String;
+      }
+      &.se {
+        // Escape sequences -> Str::Escape
+        // ----------------
+        // i.e. $$, $_, $i, $n, $p, $t and "".
+        color: $ALAN-Escapes;
+      }
+      &.si {
+        // Interpolations -> Str::Interpol
+        // --------------
+        // i.e. $<n> $+<n>, $0<n>, $-<n>, $!<n>, $a, $l, $o and $v.
+        color: $ALAN-Interpolations;
+      }
+      // --------------
+      //    Comments
+      // --------------
+      &.c1 {
+        // Single-line comments -> Comment::Single
+        // --------------------
+        color: $ALAN-Comments;
+      }
+      &.cm {
+        // Block comments -> Comment::Multiline
+        // --------------
+        color: $ALAN-Comments;
+      }
+      // --------------------------
+      //    Keywords & Built-ins
+      // --------------------------
+      &.kr {
+        // Alan Keywords -> Keyword::Reserved
+        // -------------
+        color: $ALAN-Keywords;
+      }
+      &.nb {
+        // Predefined Classes -> Name::Builtin
+        // ------------------
+        color: $ALAN-Builtin-Classes;
+      }
+      &.nx {
+        // Predefined Instances -> Name::Other
+        // --------------------
+        // i.e. the 'hero'
+        color: $ALAN-Hero;
+      }
+    }
+    // =========================================================================
+    //                            Highlight Markers
+    // =========================================================================
+    // Highlighter marker effects to mark code lines or segments.
+    // Mainly used in "ALAN Beginner's Guide" to mark added code in the sources.
+    //
+    // Two colors are passed to the mixins to create a gradient. If both colors
+    // are identical a plain background will be defined instead.
+
+    // -------------------------------------------------------------------------
+    // Yellow Marker: <mark>
+    // -------------------------------------------------------------------------
+    // Let's add to the <mark> tag a smeared fluorescent marker effect.
+
+    @include MarkerMark($ALAN-MarkerYellow1, $ALAN-MarkerYellow2);
+
+    // -------------------------------------------------------------------------
+    // Green Marker: <span class="green">
+    // -------------------------------------------------------------------------
+    // Let's add to the <mark> tag a smeared fluorescent marker effect.
+    @include MarkerSpan('green', $ALAN-MarkerGreen1, $ALAN-MarkerGreen2);
+  }
+}
+
+// EOF //
diff --git a/_assets-src/sass/_rouge-theme_alan-lib.scss b/_assets-src/sass/_rouge-theme_alan-lib.scss
@@ -0,0 +1,35 @@
+// *****************************************************************************
+/* Rouge Theme for Alan Library -- Base16 Eighties, by Chris Kempson */
+// *****************************************************************************
+
+// Provides an alternative dark theme for Alan code with "role=lib" to visually
+// distinguish code excerpts from a library or third party extensions.
+
+$ALAN-Role: 'lib';
+
+@import 'base16-eighties';  // Base16 Eighties color scheme.
+
+$ALAN-Background:      $base00;
+$ALAN-Normal-Text:     $base05;
+$ALAN-IDs:             $ALAN-Normal-Text;
+$ALAN-Numbers:         $base09;
+$ALAN-Operators:       $ALAN-Normal-Text;
+$ALAN-LineNumbers:     $base03;
+$ALAN-Escapes:         $base09; // $p $n $i $t $a $l $v $$
+$ALAN-Interpolations:  $base0F; // $<n> $+<n> $0<n> $-<n> $!<n> $o
+$ALAN-String:          $base0B;
+$ALAN-StrDelimiter:    $ALAN-StrDelimiter;
+$ALAN-Operators:       $ALAN-Normal-Text;
+$ALAN-Keywords:        $base08;
+$ALAN-Punctuation:     $ALAN-Keywords;
+$ALAN-Builtin-Classes: $base0A;
+$ALAN-Hero:            $base0D;
+
+// Context Vars:
+$ALAN-Border-Color:    $base04;
+$ALAN-Callouts-BG:     white;
+$ALAN-Callouts-FG:     black;
+
+@import 'rouge-template-alan'; // Reusable template for Alan themes.
+
+// EOF //
diff --git a/_assets-src/sass/_rouge-theme_alan-tutorial.scss b/_assets-src/sass/_rouge-theme_alan-tutorial.scss
@@ -0,0 +1,44 @@
+// *****************************************************************************
+/* Rouge Theme for Alan tutorial -- Base16 Google, by Seth Wright */
+// *****************************************************************************
+
+// Provides an alternative extra-light theme for Alan code with "role=tutorial"
+// to visually distinguish between code of a tutorial file from generic
+// examples.
+
+$ALAN-Role: 'tutorial';
+
+@import 'base16-google-dark';  // Base16 Google Dark color scheme (light).
+
+$ALAN-Background:      $base07;
+$ALAN-Normal-Text:     $base02;
+$ALAN-IDs:             $ALAN-Normal-Text;
+$ALAN-Numbers:         $ALAN-Normal-Text; //$base09;
+$ALAN-Operators:       $ALAN-Normal-Text;
+$ALAN-LineNumbers:     $base05;
+$ALAN-Comments:        $base03;
+$ALAN-String:          $base0B;
+$ALAN-StrDelimiter:    $ALAN-String;
+$ALAN-Escapes:         $base09; // $p $n $i $t $a $l $v $$
+$ALAN-Interpolations:  $base0F; // $<n> $+<n> $0<n> $-<n> $!<n> $o
+$ALAN-Keywords:        $base08;
+$ALAN-Punctuation:     $ALAN-Keywords;
+$ALAN-Builtin-Classes: $base0A;
+$ALAN-Hero:            $base0D;
+
+// Context Vars:
+$ALAN-Border-Color:    $base06;
+$ALAN-Callouts-BG:     black;
+$ALAN-Callouts-FG:     white;
+
+// -----------------
+// Highlight Markers
+// -----------------
+$ALAN-MarkerYellow1: #F5FF87;
+$ALAN-MarkerYellow2: $ALAN-MarkerYellow1;
+$ALAN-MarkerGreen1:  lighten($base0B, 60%);
+$ALAN-MarkerGreen2:  $ALAN-MarkerGreen1;
+
+@import 'rouge-template-alan'; // Reusable template for Alan themes.
+
+// EOF //
diff --git a/_assets-src/sass/build.sh b/_assets-src/sass/build.sh
@@ -15,6 +15,7 @@ rm -f *.css docinfo*.html
 ########################
 sass highlight-js.scss ../../_assets/hjs/styles/github.min.css
 sass highlight.scss highlight.css
+sass rouge.scss rouge.css
 
 ## Create docinfo Files from CSS
 ################################
@@ -24,6 +25,11 @@ cat highlight.css >> docinfo_HL.html
 echo "</style>"   >> docinfo_HL.html
 
 
+echo "<style>"    >  docinfo_Rouge.html
+cat rouge.css     >> docinfo_Rouge.html
+echo "</style>"   >> docinfo_Rouge.html
+
+
 if [[ $(uname -s) == MINGW* ]];then
 	unix2dos docinfo*.html
 fi
@@ -39,6 +45,12 @@ fi
 
 DestDirs="alanguide conversion"
 for folder in ${DestDirs[*]} ; do
-	echo "../../$folder/"
+	echo "../../$folder/docinfo.html"
 	cp docinfo_HL.html "../../$folder/docinfo.html"
 done
+
+# =====
+# Rouge
+# =====
+
+cp docinfo_Rouge.html "../../_assets/rouge/docinfo.html"