From ef8f0a96f388b4f718eda277a85b87ced6bc00bf Mon Sep 17 00:00:00 2001 From: George Cushen Date: Sun, 21 Aug 2022 10:55:47 +0100 Subject: [PATCH] feat: add support for mindmaps --- .github/contributing.md | 24 +++++ .../content/writing-markdown-latex/index.md | 102 ++++++++++++++++-- modules/wowchemy/assets/js/mathjax-config.js | 4 + .../_markup/render-codeblock-markmap.html | 4 + .../wowchemy/layouts/partials/site_js.html | 23 ++++ 5 files changed, 150 insertions(+), 7 deletions(-) create mode 100644 modules/wowchemy/layouts/_default/_markup/render-codeblock-markmap.html diff --git a/.github/contributing.md b/.github/contributing.md index 38be8bdd..7255a78d 100644 --- a/.github/contributing.md +++ b/.github/contributing.md @@ -128,6 +128,30 @@ If you're not a developer there are still plenty of ways that you can help. We a - Hosting local Wowchemy themed events or meetups - Promoting Wowchemy to others by blogging, vlogging, code streaming, talking etc. +## Best practices + +To create a consistent experience for all contributors and help prevent bugs, we have some best practices. + +### Conventional Commits Specification + +Please follow the [Conventional Commits Specification](https://www.conventionalcommits.org/en/v1.0.0/). + +For example: + +- new feature: `feat: add the X parameter` +- bug fix: `fix: typo in implementation of X parameter` +- docs: `docs: document the X parameter` +- style: `style: change font color from black to blue` +- build-related: `chore: rebuild JS assets` + +### Linting and formatting + +```sh +yarn install +yarn run lint +yarn run format +``` + ## Scope Please be _mindful_ that although we encourage feature requests, we cannot expand the scope of the project in every possible direction. There will be feature requests that don't make the roadmap. diff --git a/docs/en/content/writing-markdown-latex/index.md b/docs/en/content/writing-markdown-latex/index.md index 25712272..633c76ab 100644 --- a/docs/en/content/writing-markdown-latex/index.md +++ b/docs/en/content/writing-markdown-latex/index.md @@ -2,7 +2,7 @@ title: "📸 Page Elements: Writing content with Markdown, LaTeX, and Shortcodes" linktitle: 📸 Page Elements date: 2016-04-17 -type: book +lastmod: 2022-08-21 weight: 30 math: true summary: Learn how to format content with Markdown, write math with LaTeX, add citations, and embed rich media such as image galleries, videos, podcasts, and Twitter feeds. @@ -365,16 +365,22 @@ The following kinds of video may be added to a page. **Local video file** -Videos may be added to a page by either placing them in your `static/media/` media library or in your [page's folder](https://gohugo.io/content-management/page-bundles/), and then referencing them using one of the following notations. +Videos may be added to a page by either placing them in your `assets/media/` media library or in your [page's folder](https://gohugo.io/content-management/page-bundles/), and then referencing them using one of the following notations. -A video from your `static/media/` media library: - - {{}} - -A video within a [page's folder](https://gohugo.io/content-management/page-bundles/) (e.g. `content/post/hello/`): +A video from your page folder or your `assets/media/` media library: {{}} +Wowchemy will search for the video in your page folder and your media library at `assets/media/`. + +**External video file** + + {{}} + +If you don't want video controls, remove the `controls` parameter and the video will autoplay with looping (great for memes!). + +Note that browsers will block autoplay if the video contains sound. + **Youtube**: {{}} @@ -395,6 +401,88 @@ Demo: You might also find the [Plotly JSON Editor](http://plotly-json-editor.getforge.io/) useful. +### Mindmaps + +Wowchemy supports a Markdown extension for mindmaps. + +Simply insert a Markdown `markmap` code block and optionally set the height of the mindmap as shown in the first example below. + +A simple mindmap defined as a Markdown list: + +
+
+
+```markmap {height="200px"}
+- Hugo Modules
+  - wowchemy
+  - wowchemy-plugins-netlify
+  - wowchemy-plugins-netlify-cms
+  - wowchemy-plugins-reveal
+```
+
+
+
+ +renders as + +```markmap {height="200px"} +- Hugo Modules + - wowchemy + - wowchemy-plugins-netlify + - wowchemy-plugins-netlify-cms + - wowchemy-plugins-reveal +``` + +A more advanced mindmap with formatting, code blocks, and math: + +
+
+
+```markmap
+- Mindmaps
+  - Links
+    - [Wowchemy Docs](https://wowchemy.com/docs/)
+    - [Discord Community](https://discord.gg/z8wNYzb)
+    - [GitHub](https://github.com/wowchemy/wowchemy-hugo-themes)
+  - Features
+    - Markdown formatting
+    - **inline** ~~text~~ *styles*
+    - multiline
+      text
+    - `inline code`
+    -
+      ```js
+      console.log('hello');
+      console.log('code block');
+      ```
+    - Math: $x = {-b \pm \sqrt{b^2-4ac} \over 2a}$
+```
+
+
+
+ +renders as + +```markmap +- Mindmaps + - Links + - [Wowchemy Docs](https://wowchemy.com/docs/) + - [Discord Community](https://discord.gg/z8wNYzb) + - [GitHub](https://github.com/wowchemy/wowchemy-hugo-themes) + - Features + - Markdown formatting + - **inline** ~~text~~ *styles* + - multiline + text + - `inline code` + - + ```js + console.log('hello'); + console.log('code block'); + ``` + - Math: $x = {-b \pm \sqrt{b^2-4ac} \over 2a}$ +``` + ## Embed Documents The following kinds of document may be embedded into a page. diff --git a/modules/wowchemy/assets/js/mathjax-config.js b/modules/wowchemy/assets/js/mathjax-config.js index 2f039fdc..45d56689 100644 --- a/modules/wowchemy/assets/js/mathjax-config.js +++ b/modules/wowchemy/assets/js/mathjax-config.js @@ -4,6 +4,10 @@ // - The CommonHTML.linebreaks option is not yet implemented (but may be in a future release) // - The TeX.noUndefined.attributes option is not yet implemented (but may be in a future release) window.MathJax = { + options: { + // Don't render math in mindmaps as Markmap has its own math renderer. + ignoreHtmlClass: 'markmap', + }, tex: { inlineMath: [ ['$', '$'], diff --git a/modules/wowchemy/layouts/_default/_markup/render-codeblock-markmap.html b/modules/wowchemy/layouts/_default/_markup/render-codeblock-markmap.html new file mode 100644 index 00000000..651963db --- /dev/null +++ b/modules/wowchemy/layouts/_default/_markup/render-codeblock-markmap.html @@ -0,0 +1,4 @@ +
+{{- .Inner | safeHTML }} +
+{{ .Page.Store.Set "has_markmap" true }} diff --git a/modules/wowchemy/layouts/partials/site_js.html b/modules/wowchemy/layouts/partials/site_js.html index 8eff4649..ef68a87f 100644 --- a/modules/wowchemy/layouts/partials/site_js.html +++ b/modules/wowchemy/layouts/partials/site_js.html @@ -136,6 +136,29 @@ {{- end -}} +{{/* Mindmaps */}} +{{ if .Page.Store.Get "has_markmap" -}} + + + +{{ end -}} + {{ $js_license := printf "/*! Wowchemy v%s | https://wowchemy.com/ */\n" site.Data.wowchemy.version }} {{ $js_license := $js_license | printf "%s/*! Copyright 2016-present George Cushen (https://georgecushen.com/) */\n" }} {{ $js_license := $js_license | printf "%s/*! License: https://github.com/wowchemy/wowchemy-hugo-themes/blob/main/LICENSE.md */\n" }}