forked from cadence/breezewiki-docs
163 lines
6.1 KiB
Racket
163 lines
6.1 KiB
Racket
#lang scribble/base
|
|
|
|
@(require scribble/manual scribble/core racket/list)
|
|
@(define (code . pre-content) (elem (apply literal pre-content) #:style 'tt))
|
|
|
|
@title{BreezeWiki Documentation}
|
|
|
|
@url{https://breezewiki.com}
|
|
|
|
@local-table-of-contents[]
|
|
|
|
@; -----------------------------------------------------------------------------
|
|
|
|
@section{Links}
|
|
|
|
@subsection{Official}
|
|
|
|
@tabular[#:style (style "user-table" null)
|
|
(map (λ (row) (list (first row) (if (string? (second row)) (url (second row)) (second row))))
|
|
`(("Official website" "https://breezewiki.com")
|
|
("Community" "https://matrix.to/#/#breezewiki:cadence.moe")
|
|
("How to bug report or feature request" ,(Secref "Reporting Bugs"))
|
|
("Planned features" "https://todo.sr.ht/~cadence/breezewiki-todo")
|
|
("Source code" "https://gitdab.com/cadence/breezewiki")
|
|
("Documentation source" "https://gitdab.com/cadence/breezewiki-docs")
|
|
))]
|
|
|
|
@subsection{Instances}
|
|
|
|
@tabular[#:style (style "user-table instance-list user-table--title" null)
|
|
(map (λ (row) (list (if (string? (second row)) (hyperlink (second row) (first row)) (first row))
|
|
(if (string? (third row)) (url (third row)) (third row))))
|
|
`((,(literal "Hoster") #f ,(literal "Link"))
|
|
("Cadence" "https://cadence.moe" "https://breezewiki.com")
|
|
("PussTheCat" "https://pussthecat.org" "https://breezewiki.pussthecat.org")
|
|
))]
|
|
|
|
@subsection{Tools}
|
|
|
|
@subsubsection{Cadence's redirector}
|
|
|
|
@url{https://docs.breezewiki.com/files/redirector.user.js}
|
|
|
|
Displays a giant banner with a link to send you to BreezeWiki.
|
|
|
|
@subsubsection{barr0w's redirector}
|
|
|
|
@url{http://alphamethyl.barr0w.net/~barrow/src/barrownet_ca_redirector/breezewiki_redirector.user.js}
|
|
|
|
Just sends you to BreezeWiki.
|
|
|
|
@; -----------------------------------------------------------------------------
|
|
|
|
@section[#:tag "Reporting Bugs"]{Reporting Bugs}
|
|
|
|
Bug reports are important, and so are feature requests! Thank you for your interest. Here's how to send in yours.
|
|
|
|
There is the @italic{mailing list} which is the first line for people like you to report to. Once a bug is confirmed, I will copy it onto the @italic{todo tracker} as a task item.
|
|
|
|
Please spend one minute @hyperlink["https://todo.sr.ht/~cadence/breezewiki-todo" "checking the todo tracker"] so you don't submit a duplicate of somebody else's report.
|
|
|
|
For real-time chat with the community, check out @url{https://matrix.to/#/#breezewiki:cadence.moe}.
|
|
|
|
@subsection{Actually sending a report}
|
|
|
|
To actually send in your report, compose an email to @hyperlink["mailto:~cadence/breezewiki-discuss@lists.sr.ht" "~cadence/breezewiki-discuss@lists.sr.ht"] with a useful subject line and a description.
|
|
|
|
Please make sure to include the following information:
|
|
|
|
@itemlist[
|
|
@item{Which URL can I visit to see it for myself?}
|
|
@item{Which part of the page are you talking about?}
|
|
@item{Does it happen every time?}
|
|
]
|
|
|
|
Thanks!
|
|
|
|
@; -----------------------------------------------------------------------------
|
|
|
|
@section{Running}
|
|
|
|
@subsection{Running a compiled executable}
|
|
|
|
This method is recommended for people who do not want to edit the source code.
|
|
|
|
The distribution includes the Racket runtime, libraries, and everything else needed to run BreezeWiki.
|
|
|
|
@itemlist[#:style 'ordered
|
|
@item{Download the distribution: @url{https://docs.breezewiki.com/files/breezewiki-dist.tar.gz}}
|
|
@item{Unpack the archive.}
|
|
@item{Execute the binary @code{breezewiki-dist/bin/dist}.}
|
|
]
|
|
|
|
@subsection{Running the source code}
|
|
|
|
This method is recommended for people who want to edit the source code, or for people who can't use the compiled distribution.
|
|
|
|
@itemlist[#:style 'ordered
|
|
@item{Install Racket. Please install the latest version. 8.4 or later is required.}
|
|
@item{Clone the repository from @url{https://gitdab.com/cadence/breezewiki}.}
|
|
@item{Run @code{raco pkg install --auto --skip-installed} in the repository to install dependencies.}
|
|
]
|
|
|
|
@nested[#:style (style "block-note" null)]{If building in an automated environment, like CI, use the flags @code{--batch --auto --no-docs --skip-installed}.}
|
|
|
|
Now you can start BreezeWiki using one of the following methods.
|
|
|
|
@itemlist[
|
|
@item{Run @code{racket dist.rkt} to start BreezeWiki.}
|
|
@item{Evaluate @code{breezewiki.rkt} in DrRacket or in the Racket REPL to start BreezeWiki with module hot-reloading. Helpful for development!}
|
|
]
|
|
|
|
To be able to start up BreezeWiki faster, use @code{raco make dist.rkt} to byte-compile individual files.
|
|
|
|
@; -----------------------------------------------------------------------------
|
|
|
|
@section{Configuration}
|
|
|
|
@subsection{File}
|
|
|
|
Configuration options are added to the @code{config.ini} file. It is a regular INI file.
|
|
|
|
If you do not specify a specific option, the internal default will be used. If the file is missing or empty, all defaults will be used.
|
|
|
|
If you're using a compiled distribution of BreezeWiki, the main @code{config.ini} file will actually be a symlink to the real location of the file. Make sure not to erase the symlink, or your settings will be ignored!
|
|
|
|
@subsection{Example}
|
|
|
|
Here is an example configuration file. It shows all the available settings and all their defaults.
|
|
@verbatim{
|
|
canonical_origin =
|
|
debug = false
|
|
port = 10416
|
|
}
|
|
|
|
@subsection{Format}
|
|
|
|
@itemlist[
|
|
@item{A line with an equals sign @code{=} defines one setting.}
|
|
@item{The text before the equals sign is the @italic{key}.}
|
|
@item{The text after the equals sign is the @italic{value}. It may be empty.}
|
|
@item{Quote marks are optional - they are never necessary.}
|
|
@item{Spacing around the equals sign is optional.}
|
|
@item{@italic{False} values are represented by either empty space, or the text @code{false}. Anything else is @italic{True}.}
|
|
]
|
|
|
|
@subsection{Detailed Options}
|
|
|
|
@defthing[canonical_origin value #:value ""]{
|
|
The URL that the homepage of the instance is intended to be accessed at.
|
|
|
|
For example, @code{https://breezewiki.com}
|
|
}
|
|
|
|
@defthing[debug boolean #:value false]{
|
|
Enables debugging mode, for debugging BreezeWiki during development.
|
|
|
|
Enables more runtime checks and more verbose output. Turns off some browser caching.
|
|
}
|
|
|
|
@defthing[port value #:value "10416"]{
|
|
Which port to run the server on.
|
|
}
|