Merge pull request #13 from RoboKiwi/feature/monaco-code-blocks

Syntax highlighting using Monaco editor

Author: DavidMoore

.vscode/dictionary.txt

@@ -0,0 +1,2 @@
+# Custom Dictionary Words
+RoboKiwi

.vscode/settings.json

@@ -0,0 +1,10 @@
+{
+    "cSpell.customDictionaries": {
+        "custom-dictionary-workspace": {
+            "name": "custom-dictionary-workspace",
+            "path": "${workspaceFolder:SiteGen}/.vscode/dictionary.txt",
+            "addWords": true,
+            "scope": "workspace"
+        }
+    }
+}

README.md

@@ -7,14 +7,17 @@ SiteGen is a .NET-based static site generator.
 ## Features
 
 - Markdown support
-- Pygments syntax highlighting
+- Syntax Highlighting
+  - Pygments
+  - Prism.js
+  - Monaco
 - Mermaid diagrams
 - Razor templates
 - Rich site hierarchy model, for building navigation in your templates
 - Table of Contents
 - Extensible
 
-## Usage
+## Get Started
 
 In your ASP.NET website, reference `SiteGen.Core`.
 
@@ -51,7 +54,18 @@ app.UseSiteGen();
 app.Run();
 ```
 
-Add your `.md` files in a `content` folder, and your static assets in `static`.
+Configure paths in `appsettings.json`:
+
+```json
+{
+  "ContentPaths": [ "content" ],
+  "StaticPaths": [ "static", "wwwroot" ]
+}
+```
+
+Add your `.md` files into the `content` folder, and your static assets in `static` or `wwwroot`.
+
+Add a `Page.cshtml` to 'Pages/Shared' (for Razor Pages) or 'Views/Home' or 'Views/Shared' (for MVC) folder.
 
 If you generate client-side css and javascript, you can distribute your built artifacts to either the `static` or `wwwroot` folders.
 
@@ -69,6 +83,14 @@ dotnet tool install --local SiteGen.Cli
 - Launch your website and bind to port :5000
 - Run `dotnet sitegen` to crawl your site and publish the static resources to `/public`
 
+# How it works
+
+SiteGen registers itself as a default fallback route. This allows your website to implement its own routes which will take precedence.
+
+By default, SiteGen will generate a site map from the markdown files it finds in the configured content directories.
+
+The SiteGen fallback route it for its in-built HomeController and Page action. This is why you must implement a default Page.cshtml view.
+
 # Services
 
 # Interactive, hosted browser scraping with Playwright

SiteGen.sln

@@ -15,8 +15,7 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "SiteGen.Extensions.Markdown
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{02EA681E-C7D8-13C7-8484-4AC65E1B71E8}"
 	ProjectSection(SolutionItems) = preProject
-		LICENSE.txt = LICENSE.txt
-		README.md = README.md
+		docs\syntax-highlighting.md = docs\syntax-highlighting.md
 	EndProjectSection
 EndProject
 Global

docs/syntax-highlighting.md

@@ -0,0 +1,74 @@
+# Syntax highlighting
+
+Syntax highlighting is applied to fenced code blocks in Markdown files.
+
+````markdown
+```javascript
+console.log("Hello, world!");
+```
+````
+
+You can also apply additional arguments to the fenced code block:
+
+## Line numbers
+
+Enable or disable line numbers
+
+## Line highlighting
+
+Highlight specific lines in the code block
+
+## Theme
+
+Override the default theme for the code block
+
+## Highlighting engine
+
+Configure the specific syntax highlighting engine to use for the code block
+
+# Themes and styles
+
+Your site must bundle (recommended) or dynamically the CSS for the syntax highlighting engine you choose.
+
+You can extract the styles using the SiteGen CLI tool.
+
+Try to include both dark and light themes, and use the `prefers-color-scheme` media query to switch between them.
+
+# Supported syntax highlighting engines
+
+Be careful configuring more than one syntax highlighting engine, as they will conflict with each other.
+
+## Pygments
+
+Pygments is written in Python.
+
+You need to have the `pygmentize` command available on your system to use it.
+
+TODO: Rewrite to use `pygments` directly via isolated Python environment.
+
+## Prism.js
+
+```csharp
+services.ConfigurePrism();
+```
+
+[Prism.js](https://prismjs.com/)
+
+## Monaco Editor
+
+```csharp
+services.ConfigureMonaco();
+```
+
+The [Monaco Editor](https://microsoft.github.io/monaco-editor/) is the code editor that powers Visual Studio Code.
+
+### Themes
+
+- `vs` Visual Studio Light (default)
+- `vs-dark` Visual Studio Dark
+- `hc-black` High Contrast Black
+- `hc-light` High Contrast Light
+
+## Pending
+
+- [Highlight.js](https://highlightjs.org/)

src/SiteGen.Cli/Command.cs

@@ -4,5 +4,6 @@ enum Command
 {
     None = 0,
     Build = 1,
-    Serve = 2
+    Serve = 2,
+    ExportCss = 4
 }

src/SiteGen.Cli/Commands/SyntaxHighlightingCss.cs

@@ -0,0 +1,23 @@
+using Microsoft.Extensions.Logging;
+using SiteGen.Core;
+
+namespace SiteGen.Cli.Commands;
+
+class SyntaxHighlightingCss : ICommandlet
+{
+    private readonly IMonacoService monaco;
+    private readonly ILogger<SyntaxHighlightingCss> logger;
+
+    public SyntaxHighlightingCss(IMonacoService monaco, ILogger<SyntaxHighlightingCss> logger)
+    {
+        this.monaco = monaco;
+        this.logger = logger;
+    }
+
+    public async Task ExecuteAsync()
+    {
+        logger.LogInformation("Generating syntax highlighting CSS...");
+        var css = await monaco.GetCssAsync("vs-dark");
+        Console.WriteLine(css);
+    }
+}

src/SiteGen.Cli/Program.cs

@@ -4,6 +4,8 @@
 using SiteGen.Cli;
 using SiteGen.Cli.Commands;
 using System.Diagnostics;
+using SiteGen.Core;
+using Microsoft.Extensions.Logging;
 
 var configBuilder = new ConfigurationBuilder();
 configBuilder.AddEnvironmentVariables();
@@ -25,9 +27,19 @@
 configuration.Bind(settings);
 
 var services = new ServiceCollection();
+
+services.AddLogging(builder => {
+    builder.AddConsole().SetMinimumLevel(LogLevel.Information);
+});
+
 services.AddSingleton(configuration);
 services.AddSingleton(settings);
 services.AddTransient<ServeCommand>();
+services.AddTransient<SyntaxHighlightingCss>();
+
+services.ConfigurePlaywright();
+
+services.AddMonaco();
 
 var serviceProviderOptions = new ServiceProviderOptions { ValidateScopes = true, ValidateOnBuild = true };
 var factory = new DefaultServiceProviderFactory(serviceProviderOptions);
@@ -44,6 +56,9 @@
     case Command.Serve:
         command = serviceProvider.GetRequiredService<ServeCommand>();
         break;
+    case Command.ExportCss:
+        command = serviceProvider.GetRequiredService<SyntaxHighlightingCss>();
+        break;
     default:
         break;
 }

src/SiteGen.Cli/SiteGen.Cli.csproj

@@ -15,6 +15,7 @@
 
     <ItemGroup>
         <ProjectReference Include="..\SiteGen.Core\SiteGen.Core.csproj" />
+        <ProjectReference Include="..\SiteGen.Extensions.Markdown.Monaco\SiteGen.Extensions.Markdown.Monaco.csproj" />
     </ItemGroup>
 
 </Project>

src/SiteGen.Core/Extensions/Markdown/Pygments/PygmentsMarkdownExtension.cs

@@ -9,7 +9,7 @@ public void Setup(MarkdownPipelineBuilder pipeline)
     {
         if (pipeline.BlockParsers.Contains<PygmentsBlockParser>()) return;
 
-        // High precendence so we can render before syntax highlighting
+        // High precedence so we can render before syntax highlighting
         pipeline.BlockParsers.Insert(0, new PygmentsBlockParser());
     }