Highlight js dark example (#171)

* use a11y theme

* example dark theme site

* update links

* add option to deploy dark site

Author: ntno

.github/workflows/pages-deploy-example-site.yml

@@ -17,6 +17,7 @@ on:
         type: choice
         options:
           - highlightjs
+          - highlightjs-dark
 
 jobs:
   deploy-highlightjs-example:
@@ -29,3 +30,14 @@ jobs:
       example-site-name: 'highlightjs'
     secrets:
       GH_DEPLOY_KEY: ${{ secrets.DEPLOY_KEY_HIGHLIGHTJS }}
+
+  deploy-highlightjs-dark-example:
+    name: Deploy ${{ inputs.example-site-name }}
+    if: inputs.example-site-name == 'highlightjs-dark'
+    uses: ntno/mkdocs-terminal/.github/workflows/reusable-pages-deploy.yml@main
+    with:
+      tag: ${{ inputs.tag }}
+      mkdocs-terminal-version: ${{ inputs.mkdocs-terminal-version }}
+      example-site-name: 'highlightjs-dark'
+    secrets:
+      GH_DEPLOY_KEY: ${{ secrets.DEPLOY_KEY_HIGHLIGHTJS_DARK }}

tests/examples/highlightjs-dark/docs/highlight.js

@@ -0,0 +1,5 @@
+window.addEventListener('load', hljs_highlight, false);
+
+function hljs_highlight() {
+    hljs.highlightAll();
+}

tests/examples/highlightjs-dark/docs/index.md

@@ -0,0 +1,50 @@
+# mkdocs-terminal with highlight.js
+
+This example site uses the [highlight.js] javascript library to add code highlighting to a page after it is loaded in the user's web browser.
+
+Please review the [highlight.js docs] for more information:
+
+- [supported languages]
+- [style options]
+- [get the latest files]
+
+[highlight.js]: https://highlightjs.org/
+[highlight.js docs]: https://highlightjs.readthedocs.io/en/latest/readme.html
+[supported languages]: https://highlightjs.readthedocs.io/en/latest/supported-languages.html
+[get the latest files]: https://cdnjs.com/libraries/highlight.js
+[style options]: https://highlightjs.org/examples
+
+## Set Up
+### Add highlight.js
+
+Specify the `highlight.js` javascript and CSS source files.  At a minimum you will need to include the main script `highlight.min.js` and stylesheet `a11y-dark.min.css`.  You should also specify language specific scripts as needed.
+
+`mkdocs.yml` excerpt:
+
+```yaml
+theme:
+  name: terminal
+  palette: dark
+
+extra_javascript:
+  - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.0/highlight.min.js
+  - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.0/languages/bash.min.js
+  - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.0/languages/javascript.min.js
+  - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.0/languages/python.min.js
+  - highlight.js
+
+extra_css:
+  - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.0/styles/a11y-dark.min.css
+```
+
+### Add Custom Highlighter Code
+
+Add a custom javascript file which will trigger the `highlight.js` library to highlight code blocks after an HTML page loads.  You can add the file to `docs/highlight.js` and reference it in the `extra_javascript` section of `mkdocs.yml`:
+
+```javascript
+window.addEventListener('load', hljs_highlight, false);
+
+function hljs_highlight() {
+    hljs.highlightAll();
+}
+```

tests/examples/highlightjs-dark/docs/sample-languages/bash.md

@@ -0,0 +1,16 @@
+# Bash
+
+Bash language highlighting with `highlight.js`:
+
+```bash
+#!/bin/bash
+echo "Today is " `date`
+
+echo -e "\nenter the path to a directory"
+read the_path
+
+echo -e "\nfiles and folders: "
+ls $the_path
+```
+
+Script adapted from Zaira Hira's ["Bash Scripting Tutorial Linux Shell Script and Command Line For Beginners"](https://www.freecodecamp.org/news/bash-scripting-tutorial-linux-shell-script-and-command-line-for-beginners/)

tests/examples/highlightjs-dark/docs/sample-languages/javascript.md

@@ -0,0 +1,12 @@
+# Javascript
+
+Javascript language highlighting with `highlight.js`:
+
+```javascript
+let score1 = 2;
+let score2 = 5;
+let averageScore = (score1 + score2) / 2.0
+console.log(averageScore)
+```
+
+Script adapted from Austin Asoluka's ["How to Use Variables and Data Types in JavaScript – Explained With Code Examples"](https://www.freecodecamp.org/news/how-to-use-variables-and-data-types-in-javascript/)

tests/examples/highlightjs-dark/docs/sample-languages/python.md

@@ -0,0 +1,23 @@
+# Python
+
+Python language highlighting with `highlight.js`:
+
+```python
+# calculate factorial of n
+def fact(n):
+
+    # no work required
+    if n == 1 or n == 0:
+        return 1
+
+    # minimum amount of work
+    return n * fact(n - 1)
+
+n = 5
+
+# calculate factorial
+factorial = fact(n)
+print(f"{n}! = {factorial}")
+```
+
+Script adapted from Palistha Singh's ["How Does Recursion Work? Explained with Code Examples"](https://www.freecodecamp.org/news/what-is-recursion/)

tests/examples/highlightjs-dark/mkdocs.yml

@@ -0,0 +1,45 @@
+site_name: mkdocs-terminal dark theme with highlight.js
+site_url: https://ntno.github.io/mkdocs-terminal-example-highlightjs-dark
+repo_url: https://github.com/ntno/mkdocs-terminal
+edit_uri_template: https://github.com/ntno/mkdocs-terminal/edit/main/tests/examples/highlightjs-dark/docs/{path}
+copyright: Copyright 2024 Natan Organick, All rights reserved
+site_author: ntno
+
+nav:
+    - Configuration: 'index.md'
+    - Languages: 
+      - Bash: 'sample-languages/bash.md'
+      - Python: 'sample-languages/python.md'
+      - Javascript: 'sample-languages/javascript.md'
+    
+plugins:
+  - git-revision-date
+
+markdown_extensions:
+  - toc:
+      baselevel: "1"
+      toc_depth: "2-4"
+      permalink: "#"
+      permalink_title: Anchor link to this section for reference
+
+theme:
+  name: terminal
+  palette: dark
+  features:
+    - footer.prev_next
+    - navigation.top.search_button.hide
+    - navigation.side.indexes
+    - revision.date
+    - revision.history
+
+extra_javascript:
+  - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.0/highlight.min.js
+  - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.0/languages/bash.min.js
+  - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.0/languages/javascript.min.js
+  - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.0/languages/python.min.js
+  - highlight.js
+
+extra_css:
+  - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.0/styles/a11y-dark.min.css
+
+              

tests/examples/highlightjs-dark/requirements.txt

@@ -0,0 +1,3 @@
+mkdocs
+mkdocs-terminal~=4.0
+mkdocs-git-revision-date-plugin

tests/examples/highlightjs/docs/index.md

@@ -5,17 +5,19 @@ This example site uses the [highlight.js] javascript library to add code highlig
 Please review the [highlight.js docs] for more information:
 
 - [supported languages]
-- [get the latest files from a CDN]
+- [style options]
+- [get the latest files]
 
 [highlight.js]: https://highlightjs.org/
 [highlight.js docs]: https://highlightjs.readthedocs.io/en/latest/readme.html
 [supported languages]: https://highlightjs.readthedocs.io/en/latest/supported-languages.html
-[get the latest files from a CDN]: https://highlightjs.readthedocs.io/en/latest/readme.html#fetch-via-cdn
+[get the latest files]: https://cdnjs.com/libraries/highlight.js
+[style options]: https://highlightjs.org/examples
 
 ## Set Up
 ### Add highlight.js
 
-Specify the `highlight.js` javascript and CSS source files.  At a minimum you will need to include the main script `highlight.min.js` and stylesheet `default.min.css`.  You should also specify language specific scripts as needed.
+Specify the `highlight.js` javascript and CSS source files.  At a minimum you will need to include the main script `highlight.min.js` and stylesheet `a11y-light.min.css`.  You should also specify language specific scripts as needed.
 
 `mkdocs.yml` excerpt:
 
@@ -31,7 +33,7 @@ extra_javascript:
   - highlight.js
 
 extra_css:
-  - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.0/styles/default.min.css
+  - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.0/styles/a11y-light.min.css
 ```
 
 ### Add Custom Highlighter Code

tests/examples/highlightjs/mkdocs.yml

@@ -39,6 +39,6 @@ extra_javascript:
   - highlight.js
 
 extra_css:
-  - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.0/styles/default.min.css
+  - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.0/styles/a11y-light.min.css