diff --git a/resources/config.edn b/resources/config.edn index 5ceccd7..c2c9161 100644 --- a/resources/config.edn +++ b/resources/config.edn @@ -33,7 +33,7 @@ :default-locale "en-GB" ;; default language used for messages :formatters {"vega" smeagol.formatting/process-vega "vis" smeagol.formatting/process-vega - "mermaid" smeagol.formatting/process-mermaid + "mermaid" smeagol.extensions.mermaid/process-mermaid "backticks" smeagol.formatting/process-backticks} :log-level :info ;; the minimum logging level; one of ;; :trace :debug :info :warn :error :fatal diff --git a/resources/public/content/Extensible Markup.md b/resources/public/content/Extensible Markup.md index 129a375..aec9e82 100644 --- a/resources/public/content/Extensible Markup.md +++ b/resources/public/content/Extensible Markup.md @@ -36,7 +36,7 @@ Data files can be uploaded in the same way as images, by using the **upload a fi Graphs can now be embedded in a page using the [Mermaid](https://mermaid-js.github.io/mermaid/#/) graph description language. The graph description should start with a line comprising three back-ticks and then the word `mermaid`, and end with a line comprising just three backticks. -Here's an example culled from the Mermaid documentation. +Here's an example culled from the Mermaid documentation. Edit this page to see the specification. ### GANTT Chart @@ -58,6 +58,14 @@ gantt Add to mermaid :1d ``` +Mermaid graph specifications can also be loaded from URLs. Here's another example; again, edit this page to see how the trick is done. + +### Class Diagram + +```mermaid +data/classes.mermaid +``` + ## Writing your own custom formatters A custom formatter is simply a Clojure function which takes a string and an integer as arguments and produces a string as output. The string is the text the user has typed into their markdown; the integer is simply a number you can use to keep track of which addition to the page this is, in order, for example, to fix up some JavaScript to render it. diff --git a/resources/public/data/classes.mermaid b/resources/public/data/classes.mermaid new file mode 100644 index 0000000..e71885a --- /dev/null +++ b/resources/public/data/classes.mermaid @@ -0,0 +1,14 @@ +classDiagram +Class01 <|-- AveryLongClass : Cool +Class03 *-- Class04 +Class05 o-- Class06 +Class07 .. Class08 +Class09 --> C2 : Where am i? +Class09 --* C3 +Class09 --|> Class07 +Class07 : equals() +Class07 : Object[] elementData +Class01 : size() +Class01 : int chimp +Class01 : int gorilla +Class08 <--> C2: Cool label diff --git a/resources/templates/wiki.html b/resources/templates/wiki.html index 7dfa3c8..ffc9b1a 100644 --- a/resources/templates/wiki.html +++ b/resources/templates/wiki.html @@ -9,7 +9,7 @@ - {% endblock %} diff --git a/src/smeagol/extensions/mermaid.clj b/src/smeagol/extensions/mermaid.clj new file mode 100644 index 0000000..9fe271b --- /dev/null +++ b/src/smeagol/extensions/mermaid.clj @@ -0,0 +1,85 @@ +(ns ^{:doc "Format Semagol's extended markdown format." + :author "Simon Brooke"} + smeagol.extensions.mermaid + (:require [smeagol.extensions.utils :refer :all] + [taoensso.timbre :as log])) + +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; +;;;; +;;;; Smeagol: a very simple Wiki engine. +;;;; +;;;; This program is free software; you can redistribute it and/or +;;;; modify it under the terms of the GNU General Public License +;;;; as published by the Free Software Foundation; either version 2 +;;;; of the License, or (at your option) any later version. +;;;; +;;;; This program is distributed in the hope that it will be useful, +;;;; but WITHOUT ANY WARRANTY; without even the implied warranty of +;;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +;;;; GNU General Public License for more details. +;;;; +;;;; You should have received a copy of the GNU General Public License +;;;; along with this program; if not, write to the Free Software +;;;; Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, +;;;; USA. +;;;; +;;;; Copyright (C) 2017 Simon Brooke +;;;; +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; +;;;; +;;;; Graphs can now be embedded in a page using the +;;;; [Mermaid](https://mermaid-js.github.io/mermaid/#/) graph description +;;;; language. The graph description should start with a line comprising three +;;;; back-ticks and then the word `mermaid`, and end with a line comprising just +;;;; three backticks. +;;;; +;;;; Here's an example culled from the Mermaid documentation. +;;;; +;;;; ### GANTT Chart +;;;; +;;;; ```mermaid +;;;; gantt +;;;; dateFormat YYYY-MM-DD +;;;; title Adding GANTT diagram functionality to mermaid +;;;; section A section +;;;; Completed task :done, des1, 2014-01-06,2014-01-08 +;;;; Active task :active, des2, 2014-01-09, 3d +;;;; Future task : des3, after des2, 5d +;;;; Future task2 : des4, after des3, 5d +;;;; section Critical tasks +;;;; Completed task in the critical line :crit, done, 2014-01-06,24h +;;;; Implement parser and jison :crit, done, after des1, 2d +;;;; Create tests for parser :crit, active, 3d +;;;; Future task in critical line :crit, 5d +;;;; Create tests for renderer :2d +;;;; Add to mermaid :1d +;;;; ``` +;;;; +;;;; Mermaid graph specifications can also be loaded from URLs. Here's another +;;;; example. +;;;; +;;;; ### Class Diagram +;;;; +;;;; ```mermaid +;;;; http://localhost:3000/data/classes.mermaid +;;;; ``` +;;;; +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; + + +(defn process-mermaid + "If this `url-or-graph-spec` is a valid URL, it is assumed to point to a plain + text file pointing to a valid `graph-spec`; otherwise, it is expected to BE a + valid `graph-spec`. + + Lightly mung this `graph-spec`, assumed to be a mermaid specification." + [^String url-or-graph-spec ^Integer index] + (let [data (resource-url-or-data->data url-or-graph-spec) + graph-spec (:data data)] + (log/info "Retrieved graph-spec from " (:from data) " `" ((:from data) data) "`") + (str "
\n" + graph-spec + "\n
"))) + +;; (fs/file? (str (nio/resource-path) "data/classes.mermaid")) +;; (slurp (str (nio/resource-path) "data/classes.mermaid")) diff --git a/src/smeagol/extensions/utils.clj b/src/smeagol/extensions/utils.clj new file mode 100644 index 0000000..06ed74c --- /dev/null +++ b/src/smeagol/extensions/utils.clj @@ -0,0 +1,72 @@ +(ns ^{:doc "Utility functions useful to extension processors." + :author "Simon Brooke"} + smeagol.extensions.utils + (:require [cemerick.url :refer (url url-encode url-decode)] + [clojure.string :as cs] + [me.raynes.fs :as fs] + [noir.io :as io] + [taoensso.timbre :as log])) + +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; +;;;; +;;;; Smeagol: a very simple Wiki engine. +;;;; +;;;; This program is free software; you can redistribute it and/or +;;;; modify it under the terms of the GNU General Public License +;;;; as published by the Free Software Foundation; either version 2 +;;;; of the License, or (at your option) any later version. +;;;; +;;;; This program is distributed in the hope that it will be useful, +;;;; but WITHOUT ANY WARRANTY; without even the implied warranty of +;;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +;;;; GNU General Public License for more details. +;;;; +;;;; You should have received a copy of the GNU General Public License +;;;; along with this program; if not, write to the Free Software +;;;; Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, +;;;; USA. +;;;; +;;;; Copyright (C) 2017 Simon Brooke +;;;; +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; + +(defn resource-url-or-data->data + "Interpret this `resource-url-or-data` string as data to be digested by a + `process-extension` function. It may be a URL or the pathname of a local + resource, in which case the content should be fetched; or it may just be + the data itself. + + Returns a map with a key `:from` whose value may be `:url`, `:resource` or + `:text`, and a key `:data` whose value is the data. There will be an + additional key being the value of the `:from` key, whose value will be the + source of the data." + [^String resource-url-or-data] + (let [default {:from :text + :text resource-url-or-data + :data resource-url-or-data}] + (try + (try + ;; is it a URL? + (let [url (str (url resource-url-or-data)) + result (slurp url)] + {:from :url + :url url + :data result}) + (catch java.net.MalformedURLException _ + ;; no. So is it a path to a local resource? + (let [t (cs/trim resource-url-or-data) + r (str (io/resource-path) t)] + (if + (fs/file? r) + {:from :resource + :resource t + :data (slurp r)} + default)))) + (catch Exception x + (log/error + "Could not read mermaid graph specification from `" + (cs/trim resource-url-or-data) + "` because " + (.getName (.getClass x)) + (.getMessage x) ) + default)))) diff --git a/src/smeagol/extensions/vega.clj b/src/smeagol/extensions/vega.clj new file mode 100644 index 0000000..e69de29 diff --git a/src/smeagol/formatting.clj b/src/smeagol/formatting.clj index 8fe3697..eca5277 100644 --- a/src/smeagol/formatting.clj +++ b/src/smeagol/formatting.clj @@ -1,4 +1,4 @@ -(ns ^{:doc "Format Semagol's enhanced markdown format." +(ns ^{:doc "Format Semagol's extended markdown format." :author "Simon Brooke"} smeagol.formatting (:require [clojure.data.json :as json] @@ -6,7 +6,8 @@ [cemerick.url :refer (url url-encode url-decode)] [clj-yaml.core :as yaml] [markdown.core :as md] - [smeagol.configuration :refer [config]])) + [smeagol.configuration :refer [config]] + [smeagol.extensions.mermaid :refer [process-mermaid]])) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;;;; @@ -85,12 +86,6 @@ ");\n//]]\n")) -(defn process-mermaid - "Lightly mung this `graph-spec`, assumed to be a mermaid specification." - [^String graph-spec ^Integer index] - (str "
\n" - graph-spec - "\n
")) (defn process-backticks