Merge pull request #959 from live-codes/markdown

syntax highlighting and mermaid diagrams in markdown

Author: hatemhosny

docs/docs/languages/markdown.mdx

@@ -100,6 +100,25 @@ export const styledMarkdownParams = {
 
 <LiveCodes params={styledMarkdownParams} height='80vh'></LiveCodes>
 
+## Code Blocks
+
+Syntax highlighting is provided for code blocks using [highlight.js](https://highlightjs.org/).
+
+## Mermaid Diagrams
+
+Mermaid diagrams are also supported. See [Mermaid documentation](https://mermaid.ai/open-source/) for usage.
+
+Example:
+
+````md
+```mermaid
+graph TD
+  A-->B
+  A-->C
+  B-->D
+```
+````
+
 ## Language Info
 
 ### Name
@@ -124,7 +143,7 @@ export const styledMarkdownParams = {
 
 ### Version
 
-`marked`: v13.0.2
+`marked`: v17.0.4
 
 ## Code Formatting
 

scripts/build.js

@@ -223,6 +223,8 @@ const iifeBuild = () =>
       'languages/liquid/lang-liquid-compiler.ts',
       'languages/lua-wasm/lang-lua-wasm-script.ts',
       'languages/malina/lang-malina-compiler.ts',
+      'languages/markdown/lang-markdown-compiler.ts',
+      'languages/markdown/lang-markdown-script.ts',
       'languages/minizinc/lang-minizinc-script.ts',
       'languages/mustache/lang-mustache-compiler.ts',
       'languages/nunjucks/lang-nunjucks-compiler.ts',

src/livecodes/languages/markdown/lang-markdown-compiler.ts

@@ -0,0 +1,41 @@
+import type { CompilerFunction } from '../../models';
+import { markedHighlightUrl, markedUrl, vendorsBaseUrl } from '../../vendors';
+import { getLanguageCustomSettings } from '../utils';
+
+(self as any).createMarkdownCompiler = (): CompilerFunction => {
+  (window as any).importScripts(markedUrl);
+  const marked = (window as any).marked;
+  let hljs: any;
+  let markedHighlight: any;
+  return async (code, { config }) => {
+    if (code.includes('```')) {
+      if (!hljs) {
+        (window as any).importScripts(vendorsBaseUrl + 'highlight.js/highlight.umd.js');
+        hljs = (window as any).hljs;
+      }
+      if (!markedHighlight) {
+        (window as any).importScripts(markedHighlightUrl);
+        markedHighlight = (window as any).markedHighlight.markedHighlight;
+      }
+      marked.use(
+        markedHighlight({
+          async: true,
+          emptyLangClass: 'hljs',
+          langPrefix: 'hljs language-',
+          async highlight(codeBlock: string, lang: string) {
+            if (lang === 'mermaid') {
+              return `<pre class="mermaid">${codeBlock}</pre><!-- mermaid -->`;
+            }
+            const language = hljs.getLanguage(lang) ? lang : 'plaintext';
+            return hljs.highlight(codeBlock, { language }).value;
+          },
+        }),
+      );
+    }
+    let html = await marked.parse(code, { ...getLanguageCustomSettings('markdown', config) });
+    html = html
+      .replace(/<pre><code class="hljs language-mermaid">/g, '')
+      .replace(/<!-- mermaid -->\s?<\/code><\/pre>/g, '');
+    return html;
+  };
+};

src/livecodes/languages/markdown/lang-markdown-script.ts

@@ -0,0 +1,16 @@
+import { highlightjsStylesUrl, mermaidCdnUrl } from '../../vendors';
+
+document.addEventListener('DOMContentLoaded', () => {
+  if (document.querySelector('pre.mermaid')) {
+    const script = document.createElement('script');
+    script.src = mermaidCdnUrl;
+    script.type = 'module';
+    document.body.appendChild(script);
+  }
+  if (document.querySelector('code.hljs')) {
+    const link = document.createElement('link');
+    link.rel = 'stylesheet';
+    link.href = highlightjsStylesUrl;
+    document.head.appendChild(link);
+  }
+});

src/livecodes/languages/markdown/lang-markdown.ts

@@ -1,6 +1,5 @@
 import type { LanguageSpecs } from '../../models';
-import { getLanguageCustomSettings } from '../../utils';
-import { codeMirrorBaseUrl, markedUrl } from '../../vendors';
+import { codeMirrorBaseUrl } from '../../vendors';
 import { parserPlugins } from '../prettier';
 
 export const markdown: LanguageSpecs = {
@@ -13,11 +12,11 @@ export const markdown: LanguageSpecs = {
     },
   },
   compiler: {
-    url: markedUrl,
-    factory:
-      () =>
-      async (code, { config }) =>
-        (window as any).marked.parse(code, { ...getLanguageCustomSettings('markdown', config) }),
+    factory: (_config, baseUrl) => {
+      (self as any).importScripts(baseUrl + '{{hash:lang-markdown-compiler.js}}');
+      return (self as any).createMarkdownCompiler();
+    },
+    scripts: ({ baseUrl }) => [baseUrl + '{{hash:lang-markdown-script.js}}'],
   },
   extensions: ['md', 'markdown', 'mdown', 'mkdn'],
   editor: 'markup',

src/livecodes/templates/starter/markdown-starter.ts

@@ -17,61 +17,106 @@ One Paragraph of project description goes here
 
 These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.
 
-### Prerequisites
+### Installation
 
-What things you need to install the software and how to install them
+Make sure you have \`python 3.10+\` and \`pip\` installed. Then run:
 
+\`\`\`bash
+pip install -r requirements.txt
+cp .env.example .env
+python manage.py migrate
 \`\`\`
-Give examples
+
+Start the development server on \`localhost:8000\`:
+
+\`\`\`bash
+python manage.py runserver
 \`\`\`
 
-### Installing
+### Usage
 
-A step by step series of examples that tell you how to get a development env running
+Give an example of getting some data out of the system or using it for a little demo
 
-Say what the step will be
+\`\`\`python
+from project_name import Client
 
-\`\`\`
-Give the example
+client = Client(api_key="your-api-key")
+resources = client.resources.list(limit=10)
+
+for resource in resources:
+    print(f"{resource.id}: {resource.name}")
 \`\`\`
 
-And repeat
+You can also use the \`--verbose\` flag for detailed output:
 
-\`\`\`
-until finished
+\`\`\`bash
+python main.py --verbose
 \`\`\`
 
-End with an example of getting some data out of the system or using it for a little demo
+### Frontend Integration
 
-## Running the tests
+The API returns \`JSON\` responses that can be consumed by any frontend:
 
-Explain how to run the automated tests for this system
+\`\`\`js
+const res = await fetch('http://localhost:8000/api/resources');
+const data = await res.json();
+console.log(data);
+\`\`\`
 
-### Break down into end to end tests
+## Overview
 
-Explain what these tests test and why
+A high-level look at how the system fits together. The \`Core API\` handles all business logic.
 
+\`\`\`mermaid
+graph TD
+    A[Client] -->|Request| B[API Gateway]
+    B --> C[Auth Service]
+    B --> D[Core API]
+    D --> E[(Database)]
+    D --> F[(Cache)]
 \`\`\`
-Give an example
+
+## Running the tests
+
+Run the full test suite with \`pytest\`:
+
+\`\`\`bash
+pytest --cov=project_name tests/
 \`\`\`
 
-### And coding style tests
+### End to end tests
 
-Explain what these tests test and why
+These tests verify the full request lifecycle from \`Client\` to \`Database\` and back.
 
+\`\`\`python
+def test_create_resource(client):
+    response = client.post("/api/resources", json={"name": "Test"})
+    assert response.status_code == 201
+    assert response.json()["name"] == "Test"
 \`\`\`
-Give an example
+
+### Coding style tests
+
+We use \`flake8\` and \`black\` to enforce consistent code style:
+
+\`\`\`bash
+flake8 project_name/
+black --check project_name/
 \`\`\`
 
 ## Deployment
 
-Add additional notes about how to deploy this on a live system
+Make sure \`Docker\` is installed, then build and run:
+
+\`\`\`bash
+docker build -t project-name .
+docker run -p 8000:8000 --env-file .env project-name
+\`\`\`
 
 ## Built With
 
-* [Dropwizard](http://www.dropwizard.io/1.0.2/docs/) - The web framework used
-* [Maven](https://maven.apache.org/) - Dependency Management
-* [ROME](https://rometools.github.io/rome/) - Used to generate RSS Feeds
+* [Django](https://www.djangoproject.com/) - The web framework used
+* [pip](https://pip.pypa.io/) - Dependency Management
 
 ## Contributing
 
@@ -83,7 +128,7 @@ We use [SemVer](http://semver.org/) for versioning. For the versions available,
 
 ## Authors
 
-* **Billie Thompson** - *Initial work* - [PurpleBooth](https://github.com/PurpleBooth)
+* **Your Name** - *Initial work* - [YourGitHub](https://github.com/your-username)
 
 See also the list of [contributors](https://github.com/your/project/contributors) who participated in this project.
 
@@ -93,12 +138,9 @@ This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md
 
 ## Acknowledgments
 
-* Hat tip to anyone whose code was used
+* Give credit to anyone whose code was used
 * Inspiration
 * etc
-
-
-Source: https://gist.github.com/PurpleBooth/109311bb0361f32d87a2
 `.trimStart(),
   },
   style: {

src/livecodes/vendors.ts

@@ -3,7 +3,7 @@ import { modulesService } from './services/modules';
 const { getUrl, getModuleUrl } = modulesService;
 
 export const vendorsBaseUrl = // 'http://127.0.0.1:8081/';
-  /* @__PURE__ */ getUrl('@live-codes/browser-compilers@0.22.6/dist/');
+  /* @__PURE__ */ getUrl('@live-codes/browser-compilers@0.22.10/dist/');
 
 export const acornUrl = /* @__PURE__ */ getUrl('acorn@8.12.1/dist/acorn.js');
 
@@ -259,6 +259,9 @@ export const graphreCdnUrl = /* @__PURE__ */ getUrl('graphre@0.1.3/dist/graphre.
 export const handlebarsBaseUrl = /* @__PURE__ */ getUrl('handlebars@4.7.8/dist/');
 
 export const highlightjsUrl = /* @__PURE__ */ getModuleUrl('highlight.js@11.11.1');
+export const highlightjsStylesUrl = /* @__PURE__ */ getUrl(
+  'highlight.js@11.11.1/styles/github.min.css',
+);
 
 export const hpccJsCdnUrl = /* @__PURE__ */ getUrl('@hpcc-js/wasm@2.13.0/dist/index.js');
 
@@ -298,7 +301,9 @@ export const lunaObjViewerStylesUrl = /* @__PURE__ */ getUrl(
 
 export const malinaBaseUrl = /* @__PURE__ */ getUrl(`malinajs@0.7.19/`);
 
-export const markedUrl = /* @__PURE__ */ getUrl('marked@13.0.2/marked.min.js');
+export const markedUrl = /* @__PURE__ */ getUrl('marked@17.0.4/lib/marked.umd.js');
+
+export const markedHighlightUrl = /* @__PURE__ */ getUrl('marked-highlight@2.2.3/lib/index.umd.js');
 
 export const mermaidCdnUrl = /* @__PURE__ */ getUrl('mermaid@10.2.2/dist/mermaid.esm.mjs');