simon/smeagol
1
0
Fork 0
mirror of https://github.com/journeyman-cc/smeagol.git synced 2026-04-12 18:05:06 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Mainly documenting the configuration file

Browse source
This commit is contained in:
Simon Brooke 2020-02-11 08:30:03 +00:00
parent ba45ea5163
commit fc4dcdb5d3
8 changed files with 120 additions and 46 deletions
Download patch file Download diff file Expand all files Collapse all files

11
resources/config.edn
View file

@ -28,22 +28,25 @@
;; ; ; ; ; ; ; ; ; ;
{
: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.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 :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
;; 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

33
resources/public/content/Configuration.md
View file

@ -1,33 +0,0 @@
Smeagol reads a configuration file, whose content should be formatted as a clojure map.
The default content is as follows:
```
{
:site-title "Smeagol" ;; overall title of the site, used in page headings
:default-locale "en-GB" ;; default language used for messages
:content-dir "/usr/local/etc/content"
;; where content is served from
:passwd "/usr/local/etc/passwd"
;; where the password file is stored
:log-level :info ;; the minimum logging level; one of
;; :trace :debug :info :warn :error :fatal
:formatters {"vega" smeagol.formatting/process-vega
"vis" smeagol.formatting/process-vega
"mermaid" smeagol.formatting/process-mermaid
"backticks" smeagol.formatting/process-backticks}
}
```
The values should be:
* `:content-dir` The directory in which your editable content is stored;
* `:default-locale` A string comprising a lower-case [ISO 639](https://en.wikipedia.org/wiki/ISO_639) code specifying a language, optionally followed by a hyphen and an upper-case [ISO 3166](https://en.wikipedia.org/wiki/ISO_3166) specifying a country.
* `:formatters` A map of formatters used in [[Extensible Markup]], q.v.
* `:log-level` The minimum level of log messages to be logged; one of `:trace :debug :info :warn :error :fatal`
* `:passwd` The path to your `passwd` file - see [[Security and authentication]];
* `:site-title` The title for your wiki.
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.
Note that all the values in the configuration can be overridden with [[Environment Variables]].

102
resources/public/content/Configuring Smeagol.md Normal file
View file

@ -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!

2
resources/public/content/Docker Image.md
View file

@ -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:
```

2
resources/public/content/User Documentation.md
View file

@ -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.

1
resources/public/content/_side-bar.md
View file

@ -1,6 +1,7 @@
* [[Introduction]]
* [[Change log]]
* [[User Documentation]]
* [[Configuring Smeagol]]
* [[Deploying Smeagol]]
* [[Developing Smeagol]]

8
resources/templates/wiki.html
View file

@ -2,10 +2,10 @@
{% block extra-headers %}
<!-- ifequal js-from ":cloudflare" -->
{% script "https://cdnjs.cloudflare.com/ajax/libs/photoswipe/4.1.3/photoswipe-ui-default.min.js" %}
{% script "https://cdnjs.cloudflare.com/ajax/libs/photoswipe/4.1.3/photoswipe.min.js" %}
{% style "vendor/node_modules/photoswipe/dist/photoswipe.css" %}
{% style "vendor/node_modules/photoswipe/dist/default-skin/default-skin.css" %}
<script src="https://cdnjs.cloudflare.com/ajax/libs/photoswipe/4.1.3/photoswipe-ui-default.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/photoswipe/4.1.3/photoswipe.min.js"></script>
{% style "/vendor/node_modules/photoswipe/dist/photoswipe.css" %}
{% style "/vendor/node_modules/photoswipe/dist/default-skin/default-skin.css" %}
<script src="https://cdnjs.cloudflare.com/ajax/libs/mermaid/8.4.6/mermaid.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/vega/5.9.1/vega.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/vega-lite/4.1.1/vega-lite.min.js"></script>