Document how to enable syntax highlighting

Resolves #3
Trinovantes · Aug 6, 2024 · 626e05e · 626e05e
1 parent f24795f
commit 626e05e
Show file tree

Hide file tree

Showing 3 changed files with 63 additions and 6 deletions.
diff --git a/README.md b/README.md
@@ -195,10 +195,14 @@ See [sphinx](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directi
        print(8/2)
 ```
 
+By default, the HTML compiler will simply output plaintext inside `<pre>` tags.
+If you wish to enable syntax highlighting, you will need to provide a `shiki` object in `RstGeneratorOptions`:
+
 ```ts
 import { getHighlighter } from 'shiki'
+import { RstToHtmlCompiler, RstGeneratorOptions } from 'rst-compiler'
 
-RstToHtmlCompiler.compile(rst, {}, {
+const generatorOptions: Partial<RstGeneratorOptions> = {
     shiki: {
         defaultLanguage: 'python',
         theme: 'min-dark',
@@ -208,7 +212,9 @@ RstToHtmlCompiler.compile(rst, {}, {
             themes: ['min-dark'],
         }),
     },
-})
+}
+
+RstToHtmlCompiler.compile(rst, {}, generatorOptions)
 ```
 
 See [docutils](https://docutils.sourceforge.io/docs/ref/rst/directives.html#code) for more information.

diff --git a/demo/components/CodePreview.vue b/demo/components/CodePreview.vue
@@ -1,8 +1,8 @@
 <script lang="ts" setup>
-import { RstToHtmlCompiler, RstToMdCompiler } from '@/RstCompiler.js'
 import { ref, watch } from 'vue'
-import { codeToHtml } from 'shiki'
+import { codeToHtml, getHighlighter } from 'shiki'
 import { useQuasar } from 'quasar'
+import { RstGeneratorOptions, RstParserOptions, RstToHtmlCompiler, RstToMdCompiler } from '@/index.js'
 
 type Tab = 'HTML_RENDER' | 'RAW_HTML' | 'RAW_MARKDOWN' | 'AST'
 const currentTab = ref<Tab>('HTML_RENDER')
@@ -66,13 +66,25 @@ watch(editorText, async(editorText) => {
         const parserOutput = htmlCompiler.parse(editorText, { disableWarnings: true })
         outputAst.value = JSON.stringify(parserOutput.root.toJSON(), undefined, 4)
 
-        const outputHtml = htmlCompiler.compile(parserOutput)
+        const parserOptions: Partial<RstParserOptions> = {}
+        const generatorOptions: Partial<RstGeneratorOptions> = {
+            shiki: {
+                theme: 'github-light',
+                transformers: [],
+                highlighter: await getHighlighter({
+                    langs: ['python', 'js'],
+                    themes: ['github-light'],
+                }),
+            },
+        }
+
+        const outputHtml = htmlCompiler.compile(parserOutput, parserOptions, generatorOptions)
         renderedHtmlPre.value = await codeToHtml(outputHtml.body, {
             lang: 'html',
             theme: 'vitesse-light',
         })
 
-        const outputMd = mdCompiler.compile(parserOutput)
+        const outputMd = mdCompiler.compile(parserOutput, parserOptions, generatorOptions)
         renderedMdPre.value = await codeToHtml(outputMd.body, {
             lang: 'markdown',
             theme: 'vitesse-light',
@@ -86,6 +98,9 @@ watch(editorText, async(editorText) => {
                 *:last-child{
                     margin-bottom:0;
                 }
+                pre{
+                    border: 1px solid #ccc;
+                }
                 </style>
                 ${outputHtml.header}
             </head>

diff --git a/demo/components/DefaultText.rst b/demo/components/DefaultText.rst
@@ -25,9 +25,45 @@ by a blank line.
 
     -- Firefly
 
+Code
++++
+
+By default, code will be generated as plaintext inside :code:`<pre>` tags
+
+However, this demo is configured to use :code:`shiki` for syntax highlighting:
+
+.. code:: js
+
+    import { getHighlighter } from 'shiki'
+    import { RstToHtmlCompiler, RstGeneratorOptions } from 'rst-compiler'
+
+    const generatorOptions: Partial<RstGeneratorOptions> = {
+        shiki: {
+            defaultLanguage: 'python',
+            theme: 'min-dark',
+            transformers: [],
+            highlighter: await getHighlighter({
+                langs: ['py', 'js', 'cpp'],
+                themes: ['min-dark'],
+            }),
+        },
+    }
+
+    RstToHtmlCompiler.compile(rst, {}, generatorOptions)
+
+Trying to render a language not specified in your :code:`shiki` options will trigger an error:
+
+.. code::
+
+    .. code:: csharp
+
+        Console.WriteLine("Hello World!");
+
 Math Equations
 +++
 
+Math equations are rendered using :code:`katex` out-of-the-box:
+
 .. container:: my-custom-class
 
     .. math::