mirror of
https://github.com/journeyman-cc/smeagol.git
synced 2026-04-12 18:05:06 +00:00
Mainly documentation, but some reorganisation to support documentation.
This commit is contained in:
parent
256cf702cf
commit
b2ee34bd8e
17 changed files with 265 additions and 309 deletions
|
|
@ -1,7 +1,14 @@
|
|||
# 1.0.4
|
||||
|
||||
* New gallery extension `pswp` using [Photoswipe](https://photoswipe.com/);
|
||||
* Automatic thumbnailing of uploaded images;
|
||||
* Javascript supporting extensions is only loaded for those pages on which the extensions are actually used;
|
||||
* Many minor bug fixes.
|
||||
|
||||
# 1.0.2
|
||||
Two fixes contributed by a user:
|
||||
|
||||
* [Configurable start page](https://github.com/journeyman-cc/smeagol/commit/b1eeecde1d0555e9b708807c63e28fac21de58c4)
|
||||
* [Fixed uploads](https://github.com/journeyman-cc/smeagol/commit/1136e792d4810fd9af8b443fdea6d6be4aeda79e)
|
||||
|
||||
Many thanks to [M Jerger](https://github.com/jerger) for these.
|
||||
Many thanks to [M Jerger](https://github.com/jerger) for these.
|
||||
|
|
|
|||
|
|
@ -1,102 +1,112 @@
|
|||
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
|
||||
|
||||
:extensions-from :local ;; where to load JavaScript libraries
|
||||
;; from: options are :local, :remote.
|
||||
: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}
|
||||
{:backticks {:formatter "smeagol.formatting/process-backticks"
|
||||
:scripts {}
|
||||
:styles {}}
|
||||
:mermaid {:formatter "smeagol.extensions.mermaid/process-mermaid"
|
||||
:scripts {:core {:local "vendor/node_modules/mermaid/dist/mermaid.min.js"
|
||||
:remote "https://cdnjs.cloudflare.com/ajax/libs/mermaid/8.4.6/mermaid.min.js"}}}
|
||||
:pswp {:formatter "smeagol.extensions.photoswipe/process-photoswipe"
|
||||
:scripts {:core {:local "vendor/node_modules/photoswipe/dist/photoswipe.min.js"
|
||||
:remote "https://cdnjs.cloudflare.com/ajax/libs/photoswipe/4.1.3/photoswipe.min.js"}
|
||||
:ui {:local "vendor/node_modules/photoswipe/dist/photoswipe-ui-default.min.js"
|
||||
:remote "https://cdnjs.cloudflare.com/ajax/libs/photoswipe/4.1.3/photoswipe-ui-default.min.js"}}
|
||||
:styles {:core {:local "vendor/node_modules/photoswipe/dist/photoswipe.css"}
|
||||
:skin {:local "vendor/node_modules/photoswipe/dist/default-skin/default-skin.css"}}}
|
||||
:test {:formatter "smeagol.extensions.test/process-test" }
|
||||
:vega {:formatter "smeagol.extensions.vega/process-vega"
|
||||
:scripts {:core {:remote "https://cdnjs.cloudflare.com/ajax/libs/vega/5.9.1/vega.min.js"}
|
||||
:lite {:remote "https://cdnjs.cloudflare.com/ajax/libs/vega-lite/4.1.1/vega-lite.min.js"}
|
||||
:embed {:remote "https://cdnjs.cloudflare.com/ajax/libs/vega-embed/6.2.2/vega-embed.min.js"}}}
|
||||
:vis {:formatter "smeagol.extensions.vega/process-vega"
|
||||
:scripts {:core {:remote "https://cdnjs.cloudflare.com/ajax/libs/vega/5.9.1/vega.min.js"}
|
||||
:lite {:remote "https://cdnjs.cloudflare.com/ajax/libs/vega-lite/4.1.1/vega-lite.min.js"}
|
||||
:embed {:remote "https://cdnjs.cloudflare.com/ajax/libs/vega-embed/6.2.2/vega-embed.min.js"}}}}
|
||||
|
||||
: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
|
||||
## :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
|
||||
## :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`.
|
||||
|
||||
This parameter may be overridden with the environment variable `SMEAGOL-DEFAULT-LOCALE`.
|
||||
## :extensions-from
|
||||
|
||||
Where javascript support for extensions should be loaded from. Valid values are `:local` and `:remote`; if `:remote` is chosen, they will generally be loaded from [CDNJS](https://cdnjs.com/).
|
||||
|
||||
## formatters
|
||||
For an intranet site with limited outside bandwidth, or if you are particularly concerned about security, choose `:local`; otherwise, `:remote` will result in faster loading of your pages.
|
||||
|
||||
Specifications for formatters for markup extensions. The exact data stored will change before Smeagol 1.1.0. TODO: update this.
|
||||
This parameter may be overridden with the environment variable `SMEAGOL_JS_FROM`.
|
||||
|
||||
## :formatters
|
||||
|
||||
## log-level
|
||||
Specifications for formatters for markup extensions.
|
||||
|
||||
For each extension, a map is stored with a key `:formatter`, whose value is the fully qualified name of the Clojure function providing the extension, `:scripts` and `:styles`, each of which hava one additional key for each JavaScript (in the case of `:scripts`) or CSS (in the case of `:styles`) file required by the plugin. Each of these per-file keys points to a final further map, with keys `:local` and `:remote`, whose values are URLs - relative, in the case of the `:local` key, absolute in the case of the `:remote`, pointing to where the required resource can be fetched from.
|
||||
|
||||
This parameter may be overridden with the environment variable `SMEAGOL_FORMATTERS`, but you'd be pretty unwise to do so unless to disable formatters altogether. Otherwise, editing the `config.edn` file would be far more convenient.
|
||||
|
||||
## :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`.
|
||||
|
||||
This parameter may be overridden with the environment variable `SMEAGOL-LOG-LEVEL`.
|
||||
## :passwd
|
||||
|
||||
## TODO: Complete this doumentation!
|
||||
The value of this key should be the path to the password file used to authenticate users. It should **NOT** be in the content directory! For most deployments it should be a file elsewhere in the file system, but it must be readable and writable by the account which runs the process serving Smeagol.
|
||||
|
||||
This parameter may be overridden with the environment variable `SMEAGOL_PASSWD`.
|
||||
|
||||
## :site-title
|
||||
|
||||
The value of this key should be the overall title of the site, which is used in page headings.
|
||||
|
||||
This parameter may be overridden with the environment variable `SMEAGOL_SITE_TITLE`.
|
||||
|
||||
## :start-page
|
||||
|
||||
The value of this key should be the name (without the `.md` extension) of the page to show when a user visits the base URL of your Smeagol installation.
|
||||
|
||||
## :thumbnails
|
||||
|
||||
The value of this key should be a map. Keys in this map should have values which are integers. By default, the key `:small` is bound to `64` and the key `:med` to 400. When an image file is uploaded, it is stored at the resolution you uploaded; but for every key in the `:thumbnails` map whose value is larger than the larger dimension of the uploaded file, scaled copies will also be stored in those sizes.
|
||||
|
|
|
|||
|
|
@ -2,23 +2,45 @@
|
|||
|
||||
You will need [Leiningen](https://github.com/technomancy/leiningen) 2.0 or above installed.
|
||||
|
||||
You will need [node](https://nodejs.org/en/) and [bower](https://bower.io/) installed.
|
||||
You will need [node](https://nodejs.org/en/) installed.
|
||||
|
||||
## Running in development
|
||||
To start a web server for the application during development, run:
|
||||
|
||||
lein bower install
|
||||
lein ring server
|
||||
```
|
||||
lein npm install
|
||||
lein ring server
|
||||
```
|
||||
|
||||
This should start a development server, and open a new window or tab in your default browser with the default page of the wiki loaded into it.
|
||||
|
||||
## Editing
|
||||
I generally use [LightTable](http://lighttable.com/) as my `Clojure` editor, but it doesn't really matter what you use; if you run Smeagol as described above, then all changes you make in the code (and save) will instantly be applied to the running system. This makes for a productive development environment.
|
||||
|
||||
## Building for deployment
|
||||
|
||||
*Important:* Always run `lein clean` before building a deployment build. Once you have deployed your deployment artifact, run `lein clean` again before continuing development.
|
||||
|
||||
### To build a standalone executable jar file
|
||||
|
||||
run:
|
||||
|
||||
```
|
||||
lein ring uberjar
|
||||
```
|
||||
|
||||
The resulting file may be run by invoking
|
||||
|
||||
```
|
||||
java -jar \[path to uberjar file\]
|
||||
```
|
||||
|
||||
## Documentation
|
||||
It is my intention that the code should be sufficiently well documented to be easy to understand. Documentation may be generated from the code by running
|
||||
|
||||
lein codox
|
||||
```
|
||||
lein codox
|
||||
```
|
||||
|
||||
## Contributing
|
||||
If you make changes to Smeagol which you think are useful, please contribute them in the form of a [pull request on github](https://help.github.com/articles/creating-a-pull-request/).
|
||||
|
|
|
|||
|
|
@ -1,18 +1,13 @@
|
|||
|
||||
|
||||
# Welcome to Smeagol!
|
||||
Smeagol is a simple Wiki engine inspired by [Gollum](https://github.com/gollum/gollum/wiki). Gollum is a Wiki engine written in Ruby, which uses a number of simple text formats including [Markdown](http://daringfireball.net/projects/markdown/), and which uses [Git](http://git-scm.com/) to provide versioning and backup. I needed a new Wiki for a project and thought Gollum would be ideal - but unfortunately it doesn't provide user authentication, which I needed, and it was simpler for me to reimplement the bits I did need in Clojure than to modify Gollum.
|
||||
|
||||
So at this stage Smeagol is a Wiki engine written in Clojure which uses Markdown as its text format, which does have user authentication, and which uses Git as its versioning and backup system.
|
||||
|
||||
## Status
|
||||
Smeagol is now a fully working small Wiki engine, and meets my own immediate needs.
|
||||
Smeagol is a hackable, extensible Wiki engine which is reasonably user-friendly. It uses [Markdown](http://daringfireball.net/projects/markdown/) as its text format, and [Git](http://git-scm.com/) to provide versioning and backup.
|
||||
|
||||
## Using Smeagol
|
||||
Read the [[User Documentation]] for an introduction to all Smeagol's features.
|
||||
|
||||
## Markup syntax
|
||||
Smeagol uses the Markdown format as provided by [markdown-clj](https://github.com/yogthos/markdown-clj), with the addition that anything enclosed in double square brackets, \[\[like this\]\], will be treated as a link into the wiki itself. Read more about [[Extensible Markup]].
|
||||
Smeagol uses the Markdown format as provided by [markdown-clj](https://github.com/yogthos/markdown-clj), with the addition that anything enclosed in double square brackets, \[\[like this\]\], will be treated as a link into the wiki itself. The markdown format is extensible, and has extensions already for inclusions, for data visualisations and for picture galleries. Read more about [[Extensible Markup]].
|
||||
|
||||
## Security and authentication
|
||||
Smeagol now has good security and authentication. While the initial password supplied with the system is not encrypted, when it is changed it will be; and passwords for new users added through the user administration pages are encrypted. Read more about [[Security and authentication]].
|
||||
|
|
@ -26,13 +21,13 @@ You can (if you're logged in) upload files, including images, using the **Upload
|
|||
|
||||
|
||||
## Running Smeagol
|
||||
You can run Smeagol from the [[Docker Image]]; alternatively you can run it from an executable jar file or as a war file in a servlet container. Read how in [[Deploying Smeagol]].
|
||||
You can run Smeagol from the [[Docker Image]]; alternatively you can run it from an executable jar file or as a war file in a servlet container. Read how about [[Configuring Smeagol]] and [[Deploying Smeagol]].
|
||||
|
||||
## Developing Smeagol
|
||||
Smeagol is an open source project; you're entitled to make changes yourself. Read more about [[Developing Smeagol]].
|
||||
Smeagol is an open source project; you're entitled to make changes yourself. Read more about [[Developing Smeagol]].
|
||||
|
||||
## License
|
||||
Copyright © 2014-2017 Simon Brooke. Licensed under the GNU General Public License,
|
||||
Copyright © 2014-2020 Simon Brooke. Licensed under the GNU General Public License,
|
||||
version 2.0 or (at your option) any later version. If you wish to incorporate
|
||||
parts of Smeagol into another open source project which uses a less restrictive
|
||||
license, please contact me; I'm open to dual licensing it.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue