Port the documentation to MkDocs

cedx · Apr 7, 2024 · 8bd5656 · 8bd5656
1 parent 1c0d0d4
commit 8bd5656
Show file tree

Hide file tree

Showing 14 changed files with 111 additions and 92 deletions.
diff --git a/.gitignore b/.gitignore
@@ -5,3 +5,4 @@
 /node_modules/
 /npm-debug.log
 /var/
+/www/
diff --git a/docs/.nojekyll b/docs/.nojekyll
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
diff --git a/docs/index.html b/docs/index.html
diff --git a/docs/README.md → docs/index.md b/docs/README.md → docs/index.md
@@ -10,7 +10,7 @@ The Akismet service requires an API key. If you are not already registered, [sig
 ### Get the library
 Install the latest version of **Akismet for JS** with [npm](https://getcomposer.org) package manager:
 
-```shell
+``` shell
 npm install @cedx/akismet
 ```
 
@@ -24,7 +24,3 @@ There are three different types of calls to [Akismet](https://akismet.com):
 3. [Submit spam](usage/submit_spam.md) and [submit ham](usage/submit_ham.md) are follow-ups to let Akismet know when it got something wrong (missed spam and false positives). These are very important, and you shouldn't develop using the Akismet API without a facility to include reporting missed spam and false positives.
 
 Before integrating this library into your application, you should [test your API calls](testing.md) to ensure a proper usage.
-
-## See also
-- [API reference](api/)
-- [npm package](https://www.npmjs.com/package/@cedx/akismet)
diff --git a/docs/installation.md b/docs/installation.md
@@ -6,7 +6,7 @@ and [npm](https://www.npmjs.com), the Node.js package manager, up and running.
 
 You can verify if you're already good to go with the following command:
 
-```shell
+``` shell
 node --version
 # v21.6.1
 ```
@@ -16,13 +16,13 @@ node --version
 ### 1. Install it
 From a command prompt, run:
 
-```shell
+``` shell
 npm install @cedx/akismet
 ```
 
 ### 2. Import it
 Now in your [JavaScript](https://developer.mozilla.org/docs/Web/JavaScript) code, you can use:
 
-```js
+``` js
 import * as akismet from "@cedx/akismet";
 ```
diff --git a/docs/styles.css b/docs/styles.css
@@ -0,0 +1,4 @@
+body {
+	--md-code-font-family: ui-monospace, monospace;
+	--md-text-font-family: ui-sans-serif, sans-serif;
+}
diff --git a/docs/testing.md b/docs/testing.md
@@ -10,7 +10,7 @@ or `Author.email` set to `"[email protected]"`. Populate all o
 The Akismet API will always return a `CheckResult.spam` response to a valid request with one of those values.
 If you receive anything else, something is wrong in your client, data, or communications.
 
-```js
+``` js
 import console from "node:console";
 import {Author, Blog, Client, Comment} from "@cedx/akismet";
 
@@ -34,7 +34,7 @@ and all other required fields populated with typical values.
 
 The Akismet API will always return a `CheckResult.ham` response. Any other response indicates a data or communication problem.
 
-```js
+``` js
 import console from "node:console";
 import {Author, AuthorRole, Blog, Client, Comment} from "@cedx/akismet";
 
@@ -58,7 +58,7 @@ Enable the `Client.isTest` option in your tests.
 That will tell Akismet not to change its behaviour based on those API calls: they will have no training effect.
 That means your tests will be somewhat repeatable, in the sense that one test won't influence subsequent calls.
 
-```js
+``` js
 import {Author, Blog, Client, Comment} from "@cedx/akismet";
 
 const blog = new Blog({url: "https://www.yourblog.com"});

diff --git a/docs/usage/check_comment.md b/docs/usage/check_comment.md
@@ -3,11 +3,11 @@ This is the call you will make the most. It takes a number of arguments and char
 and then returns a thumbs up or thumbs down. **Performance can drop dramatically if you choose to exclude data points.**
 The more data you send Akismet about each comment, the greater the accuracy. We recommend erring on the side of including too much data.
 
-```js
+``` js
 Client.checkComment(comment: Comment): Promise<CheckResult>
 ```
 
-It is important to [test Akismet](testing.md) with a significant amount of real, live data in order to draw any conclusions on accuracy.
+It is important to [test Akismet](../testing.md) with a significant amount of real, live data in order to draw any conclusions on accuracy.
 Akismet works by comparing content to genuine spam activity happening **right now** (and this is based on more than just the content itself),
 so artificially generating spam comments is not a viable approach.
 
@@ -32,7 +32,7 @@ See [Response Error Codes](https://akismet.com/developers/detailed-docs/errors)
 
 ## Example
 
-```js
+``` js
 import console from "node:console";
 import {Author, Blog, CheckResult, Client, Comment, CommentType} from "@cedx/akismet";
 
@@ -68,4 +68,4 @@ catch (error) {
 }
 ```
 
-See the [API reference](api/) for detailed information about the `Author` and `Comment` classes, and their properties.
+See the [API reference](https://docs.belin.io/akismet.js/api) for detailed information about the `Author` and `Comment` classes, and their properties.
diff --git a/docs/usage/submit_ham.md b/docs/usage/submit_ham.md
@@ -1,13 +1,13 @@
 # Submit ham
 This call is intended for the submission of false positives - items that were incorrectly classified as spam by Akismet.
-It takes identical arguments as [comment check](usage/check_comment.md) and [submit spam](usage/submit_spam.md).
+It takes identical arguments as [comment check](check_comment.md) and [submit spam](submit_spam.md).
 
-```js
+``` js
 Client.submitHam(comment: Comment): Promise<void>
 ```
 
-Remember that, as explained in the [submit spam](usage/submit_spam.md) documentation, you should ensure
-that any values you're passing here match up with the original and corresponding [comment check](usage/check_comment.md) call.
+Remember that, as explained in the [submit spam](submit_spam.md) documentation, you should ensure
+that any values you're passing here match up with the original and corresponding [comment check](check_comment.md) call.
 
 See the [Akismet API documentation](https://akismet.com/developers/detailed-docs/submit-ham-false-positives) for more information.
 
@@ -16,7 +16,7 @@ See the [Akismet API documentation](https://akismet.com/developers/detailed-docs
 ### **comment**: Comment
 The user's `Comment` to be submitted, incorrectly classified as spam.
 
-> Ideally, it should be the same object as the one passed to the original [comment check](usage/check_comment.md) API call.
+> Ideally, it should be the same object as the one passed to the original [comment check](check_comment.md) API call.
 
 ## Return value
 A `Promise` that resolves when the given `Comment` has been submitted.
@@ -30,7 +30,7 @@ See [Response Error Codes](https://akismet.com/developers/detailed-docs/errors)
 
 ## Example
 
-```js
+``` js
 import console from "node:console";
 import {Author, Blog, Client, Comment} from "@cedx/akismet";
 

diff --git a/docs/usage/submit_spam.md b/docs/usage/submit_spam.md
@@ -1,14 +1,14 @@
 # Submit spam
 This call is for submitting comments that weren't marked as spam but should have been.
 
-```js
+``` js
 Client.submitSpam(comment: Comment): Promise<void>
 ```
 
-It is very important that the values you submit with this call match those of your [comment check](usage/check_comment.md) calls as closely as possible.
+It is very important that the values you submit with this call match those of your [comment check](check_comment.md) calls as closely as possible.
 In order to learn from its mistakes, Akismet needs to match your missed spam and false positive reports
-to the original [comment check](usage/check_comment.md) API calls made when the content was first posted. While it is normal for less information
-to be available for [submit spam](usage/submit_spam.md) and [submit ham](usage/submit_ham.md) calls (most comment systems and forums will not store all metadata),
+to the original [comment check](check_comment.md) API calls made when the content was first posted. While it is normal for less information
+to be available for [submit spam](submit_spam.md) and [submit ham](submit_ham.md) calls (most comment systems and forums will not store all metadata),
 you should ensure that the values that you do send match those of the original content.
 
 See the [Akismet API documentation](https://akismet.com/developers/detailed-docs/submit-spam-missed-spam) for more information.
@@ -18,7 +18,7 @@ See the [Akismet API documentation](https://akismet.com/developers/detailed-docs
 ### **comment**: Comment
 The user's `Comment` to be submitted, incorrectly classified as ham.
 
-> Ideally, it should be the same object as the one passed to the original [comment check](usage/check_comment.md) API call.
+> Ideally, it should be the same object as the one passed to the original [comment check](check_comment.md) API call.
 
 ## Return value
 A `Promise` that resolves when the given `Comment` has been submitted.
@@ -32,7 +32,7 @@ See [Response Error Codes](https://akismet.com/developers/detailed-docs/errors)
 
 ## Example
 
-```js
+``` js
 import console from "node:console";
 import {Author, Blog, Client, Comment} from "@cedx/akismet";
 

diff --git a/docs/usage/verify_key.md b/docs/usage/verify_key.md
@@ -1,8 +1,8 @@
 # Key verification
-Key verification authenticates your API key before calling the [comment check](usage/check_comment.md),
-[submit spam](usage/submit_spam.md) or [submit ham](usage/submit_ham.md) methods.
+Key verification authenticates your API key before calling the [comment check](check_comment.md),
+[submit spam](submit_spam.md) or [submit ham](submit_ham.md) methods.
 
-```js
+``` js
 Client.verifyKey(): Promise<boolean>
 ```
 
@@ -12,7 +12,7 @@ if you will have multiple users with their own Akismet subscriptions using your
 See the [Akismet API documentation](https://akismet.com/developers/detailed-docs/key-verification) for more information.
 
 ## Parameters
-None.
+None. 
 
 ## Return value
 A `Promise` that resolves with a boolean value indicating whether the client's API key is valid.
@@ -26,7 +26,7 @@ See [Response Error Codes](https://akismet.com/developers/detailed-docs/errors)
 
 ## Example
 
-```js
+``` js
 import console from "node:console";
 import {Blog, Client} from "@cedx/akismet";
 
@@ -43,4 +43,4 @@ catch (error) {
 }
 ```
 
-See the [API reference](api/) for detailed information about the `Client` and `Blog` classes, and their properties and methods.
+See the [API reference](https://docs.belin.io/akismet.js/api) for detailed information about the `Client` and `Blog` classes, and their properties and methods.
diff --git a/etc/mkdocs.yaml b/etc/mkdocs.yaml
@@ -0,0 +1,75 @@
+site_name: Akismet for JS
+site_description: >
+  Prevent comment spam using the Akismet service, in JavaScript.
+  Add Akismet to your JavaScript applications so you don't have to worry about spam again.
+site_author: Cédric Belin - [email protected]
+site_url: https://docs.belin.io/akismet.js
+
+docs_dir: ../docs
+site_dir: ../www
+
+edit_uri: edit/main/docs/
+repo_name: cedx/akismet.js
+repo_url: https://github.com/cedx/akismet.js
+
+copyright: Copyright &copy; Cédric Belin
+extra:
+  generator: false
+  social:
+    - icon: fontawesome/solid/globe
+      link: https://belin.io
+      name: Belin.io
+    - icon: fontawesome/brands/github
+      link: https://github.com/cedx
+      name: GitHub
+    - icon: fontawesome/brands/linkedin
+      link: https://linkedin.com/in/cedxbelin
+      name: LinkedIn
+    - icon: fontawesome/brands/mastodon
+      link: https://mastodon.social/@cedx
+      name: Mastodon
+extra_css:
+  - styles.css
+
+markdown_extensions:
+  - admonition
+  - pymdownx.highlight
+  - pymdownx.inlinehilite
+  - pymdownx.superfences
+
+nav:
+  - Home: index.md
+  - Installation: installation.md
+  - Usage:
+      - Key verification: usage/verify_key.md
+      - Comment check: usage/check_comment.md
+      - Submit spam: usage/submit_spam.md
+      - Submit ham: usage/submit_ham.md
+  - Further reading:
+    - Testing: testing.md
+    - API reference: https://docs.belin.io/akismet.js/api
+  - About:
+      - Changelog: changelog.md
+      - License: license.md
+
+plugins:
+  - git-revision-date-localized
+  - search
+
+theme:
+  favicon: favicon.svg
+  features:
+    - content.action.edit
+    - content.action.view
+    - content.code.copy
+    - content.tooltips
+    - navigation.instant
+    - navigation.instant.progress
+    - navigation.sections
+    - navigation.top
+  font: false
+  logo: favicon.svg
+  name: material
+  palette:
+    accent: yellow
+    primary: yellow
diff --git a/gulpfile.js b/gulpfile.js
@@ -20,7 +20,8 @@ export async function doc() {
 	await build();
 	await $`typedoc --options etc/typedoc.js`;
 	for (const file of ["CHANGELOG.md", "LICENSE.md"]) await cp(file, `docs/${file.toLowerCase()}`);
-	return cp("docs/favicon.ico", "docs/api/favicon.ico");
+	await cp("docs/favicon.ico", "docs/api/favicon.ico");
+	return $`mkdocs build --config-file=etc/mkdocs.yaml`;
 }
 
 // Performs the static analysis of source code.