Merge branch 'feature/47' into develop

#47 is not yet fully finished, but it's sufficiently advanced to be snapshotted into the `develop` branch.
journeyman-cc · Feb 12, 2020 · 9706363 · 9706363
2 parents e00beaf + b191f40
commit 9706363
Show file tree

Hide file tree

Showing 24 changed files with 895 additions and 122 deletions.
diff --git a/project.clj b/project.clj
@@ -16,6 +16,8 @@
                  [environ "1.1.0"]
                  [hiccup "1.0.5"]
                  [im.chit/cronj "1.4.4"]
+                 [image-resizer "0.1.10"]
+                 [instaparse "1.4.10"]
                  [lib-noir "0.9.9" :exclusions [org.clojure/tools.reader]]
                  [markdown-clj "0.9.99" :exclusions [com.keminglabs/cljx]]
                  [me.raynes/fs "1.4.6"]
@@ -52,6 +54,7 @@
                        [vega-embed "6.2.2"]
                        [vega-lite "4.1.1"]
                        [mermaid "8.4.6"]
+                       [photoswipe "4.1.3"]
                        [tablesort "5.2.0"]]
         :root "resources/public/vendor"}
 

diff --git a/resources/config.edn b/resources/config.edn
@@ -28,18 +28,27 @@
 ;;      ;       ;       ;       ;       ;       ;       ;       ;       ;
 {
   :content-dir          "resources/public/content"
-  :start-page           "Introduction"
                                         ;; where content is served from.
   :default-locale       "en-GB"         ;; default language used for messages
-  :formatters           {"vega"         smeagol.formatting/process-vega
+  :formatters                           ;; formatters for processing markdown
+                                        ;; extensions.
+                        {"vega"         smeagol.formatting/process-vega
                          "vis"          smeagol.formatting/process-vega
-                         "mermaid"      smeagol.formatting/process-mermaid
-                         "backticks"    smeagol.formatting/process-backticks}
+                         "mermaid"      smeagol.extensions.mermaid/process-mermaid
+                         "backticks"    smeagol.formatting/process-backticks
+                         "pswp"         smeagol.extensions.photoswipe/process-photoswipe}
   :log-level            :info           ;; the minimum logging level; one of
                                         ;; :trace :debug :info :warn :error :fatal
-  :js-from              :cloudflare     ;; where to load JavaScript libraries
-                                        ;; from: options are :local, :cloudflare
+  :js-from              :cdnjs          ;; where to load JavaScript libraries
+                                        ;; from: options are :local, :cdnjs
   :passwd               "resources/passwd"
                                         ;; where the password file is stored
-  :site-title           "Smeagol"}      ;; overall title of the site, used in
+  :site-title           "Smeagol"       ;; overall title of the site, used in
                                         ;; page headings
+  :start-page           "Introduction"  ;; the page shown to a visitor to the
+                                        ;; root URL.
+  :thumbnails           {:small 64      ;; maximum dimension of thumbnails
+                                        ;; stored in the /small directory
+                         :med 400       ;; maximum dimension of thumbnails
+                                        ;; stored in the /med directory
+                         }}
diff --git a/resources/public/content/Configuration.md b/resources/public/content/Configuration.md
diff --git a/resources/public/content/Configuring Smeagol.md b/resources/public/content/Configuring Smeagol.md
@@ -0,0 +1,102 @@
+Smeagol's core configuration comes from a configuration file, `config.edn`, which may be overridden by [[Environment Variables]]. The default file is at `resources/config.edn`; this default can be overridden by providing an environment variable, `SMEAGOL_CONFIG`, whose value is the full or relative pathname of a suitable file.
+
+
+The default configuration file is as follows:
+
+```
+
+{
+
+  :content-dir          "resources/public/content"
+
+                                        ;; where content is served from.
+
+  :default-locale       "en-GB"         ;; default language used for messages
+
+  :formatters                           ;; formatters for processing markdown
+
+                                        ;; extensions.
+
+                        {"vega"         smeagol.formatting/process-vega
+
+                         "vis"          smeagol.formatting/process-vega
+
+                         "mermaid"      smeagol.extensions.mermaid/process-mermaid
+
+                         "backticks"    smeagol.formatting/process-backticks
+
+                         "pswp"         smeagol.formatting/process-photoswipe}
+
+  :log-level            :info           ;; the minimum logging level; one of
+
+                                        ;; :trace :debug :info :warn :error :fatal
+
+  :js-from              :cdnjs          ;; where to load JavaScript libraries
+
+                                        ;; from: options are :local, :cdnjs
+
+  :passwd               "resources/passwd"
+
+                                        ;; where the password file is stored
+
+  :site-title           "Smeagol"       ;; overall title of the site, used in
+
+                                        ;; page headings
+
+  :start-page           "Introduction"  ;; the page shown to a visitor to the
+
+                                        ;; root URL.
+
+  :thumbnails           {:small 64      ;; maximum dimension of thumbnails
+
+                                        ;; stored in the /small directory
+
+                         :med 400       ;; maximum dimension of thumbnails
+
+                                        ;; stored in the /med directory
+
+                         }}
+
+```
+
+
+## content-dir
+
+The value of `content-dir` should be the full or relative path to the content to be served: the Markdown files, and the upload directories. Full paths are advised, where possible. The directory must be readable and writable by the process running Smeagol. The default is `resources/public/conten`
+
+
+The value from the configuration file may be overridden with the value of the environment variable `SMEAGOL_CONTENT_DIR`.
+
+
+## default-locale
+
+The locale which you expect the majority of your visitors will use. Content negotiation will be done of course, and the best internationalisation file available will be used, but this sets a default for users who do not have any acceptable locale known to us. The default value is `en-GB`.
+
+
+This parameter may be overridden with the environment variable `SMEAGOL-DEFAULT-LOCALE`.
+
+
+## formatters
+
+Specifications for formatters for markup extensions. The exact data stored will change before Smeagol 1.1.0. TODO: update this.
+
+
+## log-level
+
+The level at which logging should operate. Each setting implies all of the settings more severe than itself so
+
+
+1. setting `:debug` will log all of `debug, info, warn, error` and| `fatal` messages;
+
+2. setting `:info` will log all of `info, warn, error` and| `fatal` messages;
+
+
+and so on, so that setting `:fatal` will show only messages which report reasons for Smeagol to fail.
+
+
+The default setting is `:info`.
+
+
+This parameter may be overridden with the environment variable `SMEAGOL-LOG-LEVEL`.
+
+## TODO: Complete this doumentation!
diff --git a/resources/public/content/Docker Image.md b/resources/public/content/Docker Image.md
@@ -8,7 +8,7 @@ Where 127.0.0.1 is the IP address through which you want to forward port 80 (in
 
 You can then browse to Smeagol by pointing your browser at http://localhost/.
 
-As of version 0.99.10, the Docker image is now based on the Jetty, rather than the Tomcat, deployment of Smeagol (that is to say, it runs the executable jar file). This makes for a lighter weight Docker image. All configuration can be overridden with [[Environment Variables]], which can be passed into the Docker container when the image is invoked, or from a [[Configuration]] file.
+As of version 0.99.10, the Docker image is now based on the Jetty, rather than the Tomcat, deployment of Smeagol (that is to say, it runs the executable jar file). This makes for a lighter weight Docker image. All configuration can be overridden with [[Environment Variables]], which can be passed into the Docker container when the image is invoked, or from a Configuration file, see [[Configuring Smeagol]].
 
 The `config.edn` and `passwd` files and the `content` directory are copied into `/usr/local/etc` in the Docker image, and the appropriate environment variables are set up to point to them:
 ```

diff --git a/resources/public/content/Example gallery.md b/resources/public/content/Example gallery.md
@@ -0,0 +1,60 @@
+## How this works
+
+The specification for this gallery is as follows:
+
+```
+{
+  slides: [
+    { src: 'content/uploads/g1.jpg', w: 2592, h:1944,
+      title: 'Frost on a gate, Laurieston' },
+    { src: 'content/uploads/g2.jpg', w: 2560, h:1920,
+      title: 'Feathered crystals on snow surface, Taliesin' },
+    { src: 'content/uploads/g3.jpg', w: 2560, h:1920,
+      title: 'Feathered snow on log, Taliesin' },
+    { src: 'content/uploads/g4.jpg', w: 2560, h:1920,
+      title: 'Crystaline growth on seed head, Taliesin' }],
+	options: {
+      timeToIdle: 100
+			},
+	openImmediately: true
+}
+
+```
+
+The format of the specification is [JSON](https://www.json.org/json-en.html); there are (at present) three keys, as follows
+
+### slides
+
+Most be present. The value of `slides` is a list delimited by square brackets of slide objects. For more information, see the [authoritative documentation](https://photoswipe.com/documentation/getting-started.html) under the sub heading **'Creating an Array of Slide Objects'**.
+
+### options
+
+Optional. The value of `options` is a JSON object [as documented here](https://photoswipe.com/documentation/options.html).
+
+### openImmediately
+
+Optional. If the value of `openImmediately` is `true`, the gallery will open immediately, covering the whole page. If false, only a button with the label 'Open the gallery' will be shown. Selecting this button will cause the gallery to open.
+
+## The Gallery
+
+This page holds an example Photoswipe gallery.
+
+```pswp
+{
+  slides: [
+    { src: 'content/uploads/g1.jpg', w: 2592, h:1944,
+      title: 'Frost on a gate, Laurieston' },
+    { src: 'content/uploads/g2.jpg', w: 2560, h:1920,
+      title: 'Feathered crystals on snow surface, Taliesin' },
+    { src: 'content/uploads/g3.jpg', w: 2560, h:1920,
+      title: 'Feathered snow on log, Taliesin' },
+    { src: 'content/uploads/g4.jpg', w: 2560, h:1920,
+      title: 'Crystaline growth on seed head, Taliesin' }],
+	options: {
+      timeToIdle: 100
+			},
+	openImmediately: true
+}
+
+```
+
diff --git 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,19 @@ 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
+```
+
+## Photoswipe galleries
+
+Not so much a formatter, this is an extension to allow you to embed image galleries in your markdown. To specify a gallery, use three backticks followed by `pswp`, followed on the following lines by a [Photoswipe](https://photoswipe.com/documentation/getting-started.html) specification in [JSON](https://www.json.org/json-en.html)
+followed by three backticks on a line by themselves. There is an [[Example gallery]] with the full PhotoSwipe configuration, and a [[Simplified example gallery]] using a much simpler syntax, so that you can see how this works.
+
 ## 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/content/Simplified example gallery.md b/resources/public/content/Simplified example gallery.md
@@ -0,0 +1,24 @@
+## How this works
+
+The specification for this gallery is as follows:
+
+```
+![Frost on a gate, Laurieston](content/uploads/g1.jpg)
+![Feathered crystals on snow surface, Taliesin](content/uploads/g2.jpg)
+![Feathered snow on log, Taliesin](content/uploads/g3.jpg)
+![Crystaline growth on seed head, Taliesin](content/uploads/g4.jpg)
+```
+
+That's all there is to it - a sequence of image links just as you'd write them anywhere else in the wiki.
+
+## The Gallery
+
+This page holds another example Photoswipe gallery, this time using a simpler, Markdown-based specification. Processing this specification takes more work than the full syntax used in the other [Example gallery], so the gallery may be slower to load; but it's much easier to configure.
+
+```pswp
+![Frost on a gate, Laurieston](content/uploads/g1.jpg)
+![Feathered crystals on snow surface, Taliesin](content/uploads/g2.jpg)
+![Feathered snow on log, Taliesin](content/uploads/g3.jpg)
+![Crystaline growth on seed head, Taliesin](content/uploads/g4.jpg)
+```
+
diff --git a/resources/public/content/User Documentation.md b/resources/public/content/User Documentation.md
@@ -67,7 +67,7 @@ To upload a file (including an image file), select the link `Upload a file` from
 
 Selecting the link will take you to the `Upload a file` page. This will prompt you for the file you wish to upload. Select your file, and then select the green `Save!` button.
 
-After your file has uploaded, you will be shown a link which can be copied and pasted into a Wiki page to link to that file.
+After your file has uploaded, you will be shown a link which can be copied and pasted into a Wiki page to link to that file. When you upload a PNG or JPG image file, multiple copies of the file may be saved at different resolutions, and you will be shown links to each of these. The `Upload a file` form also has a link to the list of all files which have been uploaded, to help with finding the one you're looking for!
 
 You must be logged in to upload files.
 

diff --git a/resources/public/content/_side-bar.md b/resources/public/content/_side-bar.md
@@ -1,6 +1,7 @@
 * [[Introduction]]
 * [[Change log]]
 * [[User Documentation]]
+* [[Configuring Smeagol]]
 * [[Deploying Smeagol]]
 * [[Developing Smeagol]]
 

diff --git a/resources/public/data/classes.mermaid 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