init public

.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

.github/workflows/publish.yaml

@@ -0,0 +1,40 @@
+name: Deploy to Cloudflare Pages on push to prod
+on:
+  push:
+    branches:
+      - prod
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    env:
+      GOOGLE_ANALYTICS_KEY: ${{ secrets.GOOGLE_ANALYTICS_KEY }}
+    permissions:
+      contents: read
+      deployments: write
+    name: Publish to Cloudflare Pages
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with: 
+          ref: prod
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - name: Install dependencies
+        run: pip install mkdocs-material=="9.*" mkdocs-awesome-pages-plugin mkdocs-markdownextradata-plugin
+      - name: Build site
+        run: mkdocs build
+      - name: Publish to Cloudflare Pages
+        uses: cloudflare/pages-action@v1
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          projectName: confabdocs
+          directory: site
+          # Optional: Switch what branch you are publishing to.
+          # By default this will be the branch which triggered this workflow
+          branch: main
+          # Optional: Change the Wrangler version, allows you to point to a specific version or a tag such as `beta`
+          wranglerVersion: '3'

.gitignore

@@ -0,0 +1 @@
+site/

README.md

@@ -0,0 +1,19 @@
+# Confab Docs
+
+### Documentation for Confab Comments, hosted at [docs.confabcomments.com](https://docs.confabcomments.com). See the [main Confab repo](https://github.com/nextguyover/Confab) for more information about this project.
+
+# Setting Up Dev Environment
+
+Install Python, then install mkdocs-material and required plugins using the following command:
+
+```
+pip install mkdocs-material=="9.*" mkdocs-awesome-pages-plugin mkdocs-markdownextradata-plugin
+```
+
+Make sure that `mkdocs` is accessible from the terminal, `mkdocs.exe` should be stored in a directory in PATH. `pip install` command should tell you whether the directory needs to be added to PATH.
+
+# Development and Building
+
+`mkdocs serve` to start the local server during development.
+
+`mkdocs build` to build the site.

docs/about/design.md

@@ -0,0 +1,19 @@
+# Design Philosophy
+
+## Mandatory Authentication 
+
+Requiring user authentication to create or vote on comments was chosen to alleviate the possible abuse scenarios associated with anonymous commenting. If you are interested in anonymous commenting as a features, visit the [Confab Github repo](https://github.com/{{variables.CONFAB_GITHUB_LOCATION}}) and let us know. 
+
+During the design of Confab, every effort was taken to make the authentication process as frictionless for visitors as possible. 
+
+Upon entering an email address, a link is presented to take a visitor directly to their mailbox. Furthermore, in the authentication code email that users are sent, there is a direct link that can be clicked to navigate back to your site and automatically login to Confab. In a best-case scenario, the login process takes just 3 clicks. 
+
+## Passwordless Login
+
+A passwordless authentication design was implemented to make the authentication process faster, as outlined in the previous section. Fundamentally, a user shouldn't be required to store a password for a small-scale blog or similar sites that Confab is intended for. An additional bonus to this is in the event of a data breach, passwords cannot be leaked.
+
+## Operation Scale
+
+Confab was designed for use on a small-scale site such as a personal blog. This allows the feature set and codebase to be simpler, allowing for easier maintainability. The SQLite database was also chosen for this reason, since a higher performance database is unnecessary for a low level of traffic.
+
+If you have a high-traffic site, Confab (at least in its current state) may not be the best choice for you.

docs/about/roadmap.md

@@ -0,0 +1,7 @@
+# Future Roadmap
+
+These are some features that are being considered for future versions of Confab. If there is anything below that you're interested in, let us know on our [Github repo](https://github.com/{{variables.CONFAB_GITHUB_LOCATION}}).
+
+- Chunked comment loading
+- Pages for centralised User (and Comment) management
+- Option for anonymous commenting

docs/admin-guide/abuse-mitigation/index.md

@@ -0,0 +1,46 @@
+# Abuse Mitigation
+
+As with any public-facing service, there are several abuse scenarios that Confab administrators must be aware of. This page will outline these scenarios, alongside instructions on how to utilise the built-in mitigation techniques that have been implemented in Confab.
+
+!!! tip
+    Regular backups of your Confab instance is recommended to easily recover from various abuse scenarios, as you can simply restore the state of your Confab instance at an earlier point in time. See [backup guide](../backup/index.md) for more info.
+
+## Content Abuse
+
+As with any public-facing service that hosts user-generated content, users may generate content that you do not wish to associate with your website.
+
+The first option for mitigating this risk is keeping [Admin comment notifications](../../core-functionality/admin-panel/index.md#email-comment-notification-settings) enabled. If you decide to not use the Manual Moderation Queue, this will ensure that you receive immediate notifications of any new edits/comments, so that you may take action in a timely manner.
+
+If you want to be certain that any content that you do not deem acceptable will not be presented on your website at all, or your website is a high-traffic site where visitors may see unacceptable content before you have a chance to remove it, it is recommended that you enable the [Manual Moderation Queue](../../core-functionality/manual-moderation/index.md) using the [backend configuration](../../config/index.md#manual-moderation), where all comments will require Admin approval before becoming publicly visible on the site.
+
+!!! note
+    If you have a high traffic site, Confab may not be the right choice for you. See [design philosophy](../../about/design.md#operation-scale).
+
+### Custom Usernames
+
+Users are able to set custom usernames which replace the default randomly generated username. Admins do not have any moderation functionality for custom usernames beyond banning offending users. 
+
+As such, if you prefer, custom usernames can be disabled altogether using the [backend configuration](../../config/#custom-usernames).
+
+## Resource Abuse
+
+### Comment Spam
+
+To prevent a bad actor from flooding your comments with spam, Confab has features to limit the number of comments that a user can post at one time. Two options are available, depending whether or not you have chosen to use the [Manual Moderation Queue](../../core-functionality/manual-moderation/).
+
+
+=== "Manual Moderation Enabled"
+
+    In this scenario, all new comments will be sent to the Manual Moderation Queue. A maximum limit on the number of comments by each user that can be in the Manual Moderation Queue can be set using the [backend configuration](../../config/index.md#manual-moderation).
+
+=== "Manual Moderation Disabled"
+
+    To limit the number of comments that a user can generate within a given timespan, use the [backend configuration](../../config/index.md#rate-limiting) to set a comment rate limit.
+
+### Email Spam
+
+Emails are [sent to users for various reasons](../../core-functionality/emails/index.md). To prevent your sending addresses being used for spam, and to prevent your SMTP quota being used up, Confab lets you set limits on the number of emails that can be sent.
+
+To prevent large numbers of login authentication code emails being sent (to email addresses that may not even belong to the user requesting the authentication code), use the [backend configuration](../../config/index.md#user-authentication-parameters) to set limits on the maximum number of consecutive auth code emails that can be sent.
+
+Confab also sends reply notifications to users when their own comments receive replies. To prevent this feature being used to generate spam emails, you may choose to [turn this feature off](../../core-functionality/admin-panel/index.md#user-own-replies), or, implement measures to prevent comment spam, as outlined [above](#comment-spam).

docs/admin-guide/backup/index.md

@@ -0,0 +1,13 @@
+# Backing Up Confab
+
+Regular backups ensure that if anything goes wrong with your Confab instance, whether that be recovering from a large number of [spam comments](../abuse-mitigation/index.md#comment-spam) or the database gets corrupted, you can easily roll back your instance to it's state at a previous point in time.
+
+To fully backup a Confab instance, the following files/directories must be backed up:
+
+- `Confab/appsettings.json` → Your backend configuration file
+- `Confab/Database/*` → The database files that store all comment data (1)
+    { .annotate }
+
+    1. This is the default database location, and can be customised in the [backend configuration](../../config/index.md#database-location)
+
+To restore from a previous backup, simply do a fresh Confab install, then copy the above files to their original locations.

docs/admin-guide/content-risks/index.md

@@ -0,0 +1,63 @@
+# Risks of User Generated Content
+
+## Images
+
+Images are defined in Markdown with the syntax `![](example.com/image.png)`. When a visitor loads Confab, and a comment is loaded that contains an image, the browser makes a GET request to the URL of the image to download the image to the client so that it can be displayed.
+
+This feature could be abused by a bad actor to get information about visitors to your site. All that would be required is to submit a comment that contains an image with a URL that the bad actor controlled. E.g. `![](bad-actor-domain.example.com/image.png)`. Every visitor that loaded this comment would now make a request to this URL. 
+
+To prevent this, you have several options. Manually moderating any comments that contain images is recommended. Images in comments awaiting moderation are not immediately loaded, allowing an Admin to manually verify safety.
+
+<figure markdown>
+![Moderation image placeholder](./moderation-image-placeholder.png){ width="400" }
+<figcaption>An image placeholder is shown to Admins to help evaluate the safety of the hosted URL before loading the image</figcaption>
+</figure>
+
+To send comments with images to the moderation queue, either [enable manual moderation for all comments](../../config/index.md#manual-moderation), or create an Automoderation Rule as described below in [Blocking Images](#blocking-images), with the action "Send to Manual Moderation Queue". 
+
+Since it is also possible to edit comments to change its contents, for maximum safety, [disable comment editing altogether](../../config/index.md#edits), or [block edits that contain images](#blocking-edits).
+
+In addition to safety risks, visitors may submit images that contain NSFW(1) content. If you do not wish to allow this content on your site, this is another reason to screen images manually.
+{ .annotate }
+
+1. "Not Safe For Work". Content that may be considered inappropriate or offensive
+
+### Blocking Images
+
+To block images from being posted altogether, [create an Automoderation rule](../../core-functionality/auto-moderation/index.md) with the following RegEx.
+
+#### Image Regex
+```
+!\[([^[\]]*)\]\(([^)\n\s]*)\)
+```
+
+You may choose to have the action of your Automoderation rule be to **block posting**, presenting a message such as "Images not allowed". Alternatively, you can set the Automoderation action to **send the comment to the Manual Moderation Queue**. 
+
+#### Blocking Edits
+
+If you have chosen to send comments containing images to the Manual Moderation Queue, you may also wish to block edits that contain images (since edits cannot be sent to the Manual Moderation Queue).
+
+For such a setup, you will want to use the [provided image RegEx](#image-regex) to create rules as follows.
+
+<figure markdown>
+![Image edit block moderation rule](img-edit-block-moderation-rule.png)
+<figcaption>The first rule will trigger on new comments, but not for an edit, so the second rule will block edits with an image</figcaption>
+</figure>
+
+
+## Links
+
+Links pose a degree of risk, as they can potentially navigate users to unsafe sites. Confab attempts to reduce this risk by presenting the domain that a visitor will be taken to from a link.
+
+<figure markdown>
+![Link example](link-example.png){ width="300" }
+</figure>
+
+However, if you would like to disable links entirely, an [Automoderation rule](../../core-functionality/auto-moderation/index.md) may be created using the following RegEx.
+
+#### Link Regex
+```
+(^|[^!])\[([^[\]]*)\]\(([^)\n\s]*)\)
+```
+
+*[RegEx]: Regular Expression

docs/admin-guide/index.md

@@ -0,0 +1,5 @@
+# Admin Guide
+
+This section contains information that may be useful to you as a Confab administrator. Some topics covered in this section include [Risks of User Generated Content](./content-risks/index.md), and [Abuse Mitigation](./abuse-mitigation/index.md).
+
+Before reading this section, you should familiarise yourself with the [Core Functionality](../core-functionality/index.md) of Confab, start with the [Admin Panel](../core-functionality/admin-panel/index.md), and the [Moderation Queue](../core-functionality/manual-moderation/index.md).