commit d8637554f6d690e19922b5920999c89071535624
parent 0febff09df010919ac01c1d719215f55cde843eb
Author: cblgh <cblgh@cblgh.org>
Date: Mon, 24 Oct 2022 10:04:18 +0200
polish polish, update readme with new capabilities
Diffstat:
5 files changed, 87 insertions(+), 16 deletions(-)
diff --git a/README.md b/README.md
@@ -15,11 +15,56 @@ phpBB forum communities of the mid naughties.
It was written for the purpose of powering the nascent [Merveilles community forums](https://forum.merveilles.town).
+## Config
+Cerca supports community customization.
+
+* Write a custom [about text](/defaults/sample-about.md) describing the community inhabiting the forum
+* Define your own [registration rules](/defaults/sample-rules.md), [how to verify one's account](/defaults/sample-verification-instructions.md), and link to an existing code of conduct
+* Set your own [custom logo](/defaults/sample-logo.html) (whether svg, png or emoji)
+* Create your own theme by writing plain, frameworkless [css](/html/assets/theme.css)
+
+To enable these customizations, there's a config file. To choose a config file, run cerca with
+the `--config` option; the default config file is set to `./cerca.toml`.
+
+```
+cerca --config ./configs/cerca.toml
+```
+
+The configuration format is [TOML](https://toml.io/en/) and the config is populated with the following
+defaults:
+
+```TOML
+[general]
+name = "" # whatever you want to name your forum; primarily used as display in tab titles
+conduct_url = "" # optional + recommended: if omitted, the CoC checkboxes in /register will be hidden
+language = "English" # Swedish, English. contributions for more translations welcome!
+
+[documents]
+logo = "content/logo.html" # can contain emoji, <img>, <svg> etc. see defaults/sample-logo.html in repo for instructions
+about = "content/about.md"
+rules = "content/rules.md"
+verification_explanation = "content/verification-instructions.md"
+```
+
+Content documents that are not found will be prepoulated using Cerca's [sample content
+files](/defaults). The easiest thing to do is to run Cerca once and let it populate content
+files using the samples, and then edit the files in `content/*` after the fact, before running
+Cerca again to see your changes.
+
+Either write your own configuration following the above format, or run cerca once to populate it and
+then edit the created config.
+
## Contributing
If you want to join the fun, first have a gander at the [CONTRIBUTING.md](/CONTRIBUTING.md)
document. It lays out the overall idea of the project, and outlines what kind of contributions
will help improve the project.
+### Translations
+
+Cerca supports use with different natural languages. To translate Cerca into your language, please
+have a look at the existing [translations (i18n.go)](/i18n/i18n.go) and submit yours as a
+[pull request](https://github.com/cblgh/cerca/compare).
+
## Local development
Install [golang](https://go.dev/).
@@ -27,7 +72,6 @@ Install [golang](https://go.dev/).
To launch a local instance of the forum, run those commands (linux):
- `touch temp.txt`
-- `mkdir data`
- `go run run.go --authkey 0 --allowlist temp.txt --dev`
-It should respond `Serving forum on :8277`. Just go on [http://localhost:8272](http://localhost:8272).
+It should respond `Serving forum on :8277`. Just go on [http://localhost:8277](http://localhost:8277).
diff --git a/defaults/sample-config.toml b/defaults/sample-config.toml
@@ -1,7 +1,7 @@
[general]
-name = ""
+name = "" # whatever you want to name your forum; primarily used as display in tab titles
conduct_url = "" # optional + recommended: if omitted, the CoC checkboxes in /register will be hidden
-language = "" # Swedish, English. contributions for more translations welcome!
+language = "English" # Swedish, English. contributions for more translations welcome!
[documents]
logo = "content/logo.html" # can contain emoji, <img>, <svg> etc. see defaults/sample-logo.html in repo for instructions
diff --git a/run.go b/run.go
@@ -4,6 +4,7 @@ import (
"flag"
"fmt"
"net/url"
+ "path/filepath"
"os"
"strings"
@@ -50,6 +51,11 @@ func main() {
} else if len(allowlistLocation) == 0 {
complain("please pass a file containing the verification code domain allowlist")
}
+
+ err := os.MkdirAll(filepath.Dir(dataDir), 0750)
+ if err != nil {
+ complain(fmt.Sprintf("couldn't create dir '%s'", dataDir))
+ }
allowlist := readAllowlist(allowlistLocation)
allowlist = append(allowlist, "merveilles.town")
config := util.ReadConfig(configPath)
diff --git a/server/server.go b/server/server.go
@@ -724,8 +724,6 @@ func Serve(allowlist []string, sessionKey string, isdev bool, dir string, conf t
if isdev {
developing = true
- // TODO (2022-10-18): don't overload passed in dir; just use --data instead
- dir = "./testdata/"
port = ":8277"
}
@@ -775,6 +773,7 @@ func NewServer(allowlist []string, sessionKey, dir string, config types.Config)
dbpath := filepath.Join(s.directory(), "forum.db")
db := database.InitDB(dbpath)
+ config.EnsureDefaultPaths()
// load the documents specified in the config
// iff document doesn't exist, dump a default document where it should be and read that
type triple struct { key, docpath, content string }
@@ -795,6 +794,7 @@ func NewServer(allowlist []string, sessionKey, dir string, config types.Config)
}
// TODO (2022-10-20): when receiving user request, inspect user-agent language and change language from server default
+ // for currently translated languages, see i18n/i18n.go
translator := i18n.Init(config.Community.Language)
templates := template.Must(generateTemplates(config, translator))
handler := RequestHandler{&db, session.New(sessionKey, developing), allowlist, files, config, translator, templates}
diff --git a/types/types.go b/types/types.go
@@ -1,9 +1,13 @@
package types
+import (
+ "path/filepath"
+)
+
type Config struct {
Community struct {
Name string `json:"name"`
- ConductLink string `json:"conduct_url"`
+ ConductLink string `json:"conduct_url"` // optional
Language string `json:"language"`
} `json:"general"`
@@ -15,16 +19,33 @@ type Config struct {
} `json:"documents"`
}
+// Ensure that, at the very least, default paths exist for each expected document path. Does not overwrite previously set values.
+func (c *Config) EnsureDefaultPaths() {
+ if c.Documents.AboutPath == "" {
+ c.Documents.AboutPath = filepath.Join("content", "about.md")
+ }
+ if c.Documents.RegisterRulesPath == "" {
+ c.Documents.RegisterRulesPath = filepath.Join("content", "rules.md")
+ }
+ if c.Documents.VerificationExplanationPath == "" {
+ c.Documents.VerificationExplanationPath = filepath.Join("content", "verification-instructions.md")
+ }
+ if c.Documents.LogoPath == "" {
+ c.Documents.LogoPath = filepath.Join("content", "logo.html")
+ }
+}
+
/*
-config structure
-["General"]
-Name = "Merveilles"
-ConductLink = "https://github.com/merveilles/Resources/blob/master/CONDUCT.md"
+config structure:
+["general"]
+name = "Merveilles"
+conduct_link = "https://github.com/merveilles/Resources/blob/master/CONDUCT.md"
+language = "English"
-["Documents"]
-LogoPath = "./logo.svg"
-AboutPath = "./about.md"
-RegisterRulesPath = "./rules.md"
-VerificationExplanationPath = "./verification-instructions.md"
+["documents"]
+logo = "./logo.svg"
+about = "./about.md"
+rules = "./rules.md"
+verification_instructions = "./verification-instructions.md"
*/
