70 lines
No EOL
5.5 KiB
Markdown
70 lines
No EOL
5.5 KiB
Markdown
# NIRVASH
|
|
|
|
|
|
|
|
## about
|
|
|
|
`nirvash` is a content management system (CMS) written in Go using the [quartzgun](https://nilfm.cc/git/quartzgun) library, designed to be efficient, modular, and easy to use. It uses an `Adapter` system that in theory allows almost any backend SSG to be used for actual page generation and backend storage. It's inspired by [Joost Van Der Schee](https://usecue.com)'s Usecue [CMS](https://www.usecue.com/uploads/cms_update.gif).
|
|
|
|
## installation and configuration
|
|
|
|
Clone this repository and run `go build` to build `nirvash`. Just running `./nirvash` from there, if you haven't run it before, should run the configuration wizard (it runs if the config file found in your user's config directory is missing or incomplete). The configuration file looks like:
|
|
|
|
```
|
|
adapter=eureka // one of the supported adapters, currently just eureka
|
|
root=/path/to/ssg/root // path to where your SSG content root is
|
|
assetRoot=/path/to/asset/root // path to the parent folder containing Nirvash static/ assets and templates/ directory (eg base directory of this repo)
|
|
staticRoot=/path/to/static/root // path to static file storage on your webserver
|
|
staticShowHTML=false // true or false, show HTML files in the file manager interface
|
|
staticShowHidden=false // true or false, show hidden files in the file manager interface
|
|
staticMaxUploadMB=25 // integer, maximum size in MB of files uploaded in the file manager interface
|
|
plugins=none // list of plugins to use, currently none are implemented
|
|
```
|
|
|
|
You can also set the configuration options by running eg `nirvash configure adapter=eureka root=/var/www`. Key-value pairs given on the command line are written to the configuration file, and pairs not listed are unmodified.
|
|
|
|
User management is done from the command line as well:
|
|
|
|
- `nirvash adduser username password`
|
|
- `nirvash rmuser username`
|
|
- `nirvash passwd username oldpass newpass`
|
|
|
|
## usage
|
|
|
|
Running `nirvash` without any arguments starts the webserver on port 8080.
|
|
|
|
Initially the user will be presented with the login screen; upon successful login, the application presents the navbar with these options:
|
|
|
|
- `Pages`: the default page, shows a list of existing pages - clicking one enables editing that page; a button is also presented for adding a new page. Each `Adapter` will provide different formatting help and can allow editable slugs/URLs or not (eg, the `EurekaAdapter` builds slugs/URLs directly from the page title).
|
|
- `Files`: provides an interface for managing statically hosted files. Files and directories can be added, moved, and deleted.
|
|
- `Configuration`: interface to the configuration for the `Adapter`. Each `Adapter` provides its own configuration interface with associated data types (currently supported: `int`, `float`, `string`, and `multilinestring`)
|
|
- `Build`: a simple form to build the site - build options configurable by `Adapter` are present under an accordion.
|
|
- `Deploy`: a _very_ simple form to either deploy the site or revert the current state to the deployed state
|
|
- `Logout`: logs the user out and returns to the login screen
|
|
|
|
## adapter interface
|
|
|
|
`nirvash` is extensible by `Adapter`s that can interact with almost any static site generator under the hood.
|
|
|
|
The `Adapter` interface and associated data types can be found in the [adapter.go](https://nilfm.cc/git/nirvash/tree/archetype/adapter.go) file, but the basic interface looks like this:
|
|
|
|
- `Init(cfg *Config)`: set any initial settings that need to be handled - typically import SSG data root from the `nirvash` config file and read the SSG's own config file
|
|
- `Name() string`: the name of the adapter, used for the `nirvash.conf` config file
|
|
- `EditableSlugs() bool`: whether slugs can be edited independently or are calculated based on, eg, page titles
|
|
- `BuildOptions() []string`: a list of names of the build options to present on the `/build` page
|
|
- `GetConfig() map[ConfigOption]string`: retrieves the config to present on the `/config` page
|
|
- `SetConfig(map[ConfigOption]string) error`: takes the config from the `/config` page and applies it, typically by writing it to a file
|
|
- `ListPages() map[string]string`: list the pages in the site; keys are the slugs, values are the titles
|
|
- `GetPage(slug string) Page`: given a slug, return the page data
|
|
- `FormatPage(string) string`: given the raw page data as input by the user, return HTML suitable for preview (currently unimplemented and unused)
|
|
- `FormattingHelp() string`: return a string to be inserted into a `pre` tag on the `/fmt-help` page
|
|
- `CreatePage(slug, title, content string) error`: given all the proper arguments, create a new page in the backing store (eg filesystem, db)
|
|
- `SavePage(oldSlug, newSlug, title, content string) error`: given all the proper arguments, save a page to the backing store (eg filesystem, db)
|
|
- `DeletePage(slug string) error`: given a slug, delete the corresponding page source and possibly its generated HTML, depending on the `Adapter`
|
|
- `Build(buildOptions map[string][]string) BuildStatus`: takes a map of build option names to their values and builds the site, returning a `BuildStatus` object containing the success or failure as a boolean and the detailed status (eg, the console ouptut of the build process)
|
|
- `Deploy() DeployStatus`: executes the deployment script and returns a `DeployStatus` object, analagous to a `BuildStatus`
|
|
- `Revert() RevertStatus`: executes the reversion script and returns a `RevertStatus` object, analagous to a `BuildStatus`
|
|
|
|
## license
|
|
|
|
`nirvash` is licensed under the [MIT license](./LICENSE). |