Add tocs for markdowns

.remarkrc.mjs

@@ -0,0 +1,17 @@
+import remarkToc from 'remark-toc'
+
+/**
+ * @typedef {import('remark-stringify').Options} Options
+ */
+
+const remarkConfig = {
+  /** @type {Options} */
+  settings: {
+    bullet: '-',
+    fences: true,
+    listItemIndent: 'one',
+  },
+  plugins: [[remarkToc, { maxDepth: 3 }]],
+}
+
+export default remarkConfig

CONTRIBUTING.md

@@ -1,32 +1,40 @@
+# Contributing to Locutus
+
 Thank you so much for being or becoming a Locutus contributor!
 
 Even if you have write access already, all code changes should be done via a Pull Request. This way we can peer-review,
 and also GitHub Actions can check if the code adheres to our policies already before merging it into `main`.
 
+## Table of Contents
+
+- [Contributing Checklist](#contributing-checklist)
+- [Prerequisites](#prerequisites)
+- [Clone](#clone)
+- [Install](#install)
+- [Build](#build)
+- [Test](#test)
+- [Website Development](#website-development)
+- [Releasing](#releasing)
+
 ## Contributing Checklist
 
 Here are a few pointers that could save us from disappointment, we'll try to keep it brief!
 
 1. By submitting a Pull Request you are giving Locutus permission to distribute your code under the MIT License.
-1. Please adhere to our [updated coding standards](/blog/2016/04/standard-coding-style/). Use `yarn lint` to check.
-   Code should:
-
-- Follow the [JavaScript Standard Style](https://standardjs.com/), and in addition:
-- Not have lines longer than 100 chars
-- Use `//` for comments instead of `/*`
-- Avoid using lengthy (3+ word) comments on the same line as code
-
-1. Please credit yourself in the function's header-comment:
+2. Please adhere to our coding standards. Use `yarn lint` to check.
+3. Use `//` for comments instead of `/*`
+4. Please credit yourself in the function's header-comment:
    `(original by|reimplemented by|improved by|parts by|bugfixed by|revised by|input by): Your Name (https://your.url)`
-1. If you are fixing bad behavior, or introducing new ones, please add an `example` that would fail before your patch,
-   and a `result` that passes after your patch, to the function's header-comment. We use these for website
-   documentation, as well as to generate test cases that avoid regression going forward. There should already be a few
-   ones there if you want to see how it's done.
-1. If you are contributing performance upgrades, please provide proof via e.g. <https://jsperf.com>
-1. Please keep in mind that some obvious readability improvements are sometimes unwanted for performance reasons. For
+5. If you are fixing bad behavior, or introducing new good ones, please add an `example` comment that would fail before
+   your patch, and a `result` comment that passes after your patch, to the function's header-comment. We use these for
+   website documentation, as well as to generate test cases that avoid regression going forward. There should already be
+   a few ones there if you want to see how it's done.
+6. If you are contributing performance upgrades, please provide proof via e.g. <https://jsperf.com>
+7. Please keep in mind that some obvious readability improvements are sometimes unwanted for performance reasons. For
    example, we sometimes place similar `for` loops inside `if` and `else` conditions for performance reasons, even
-   though the code could be half the size if we put the conditions inside a single loop.
-1. If you are adding a new function, please make sure to:
+   though the code could be half the size if we put the conditions inside a single loop. If we didn't comment this so
+   far, a PR for adding such a comment is very welcome however.
+8. If you are adding a new function, please make sure to:
 
 - include exactly one export with a named function, `module.exports = function functionName (param1, ...) {`
   - the file can contain more definitions (helper functions, classes, etc.), but is allowed to have only one export
@@ -39,38 +47,36 @@ Here are a few pointers that could save us from disappointment, we'll try to kee
 //   returns 1: "bar"
 ```
 
-## Locutus Development
+## Prerequisites
 
-### Clone
+We use Yarn managed by Corepack. It's recommended to alias:
 
 ```bash
-cd ~/code
-git clone git@github.com:locutusjs/locutus.git
-cd locutus
+alias yarn="corepack yarn"
 ```
 
-### Prerequisites
-
-We use yarn managed by Corepack. It's advisable to alias:
+## Clone
 
 ```bash
-alias yarn="corepack yarn"
+# cd ~/code
+git clone git@github.com:locutusjs/locutus.git
+cd locutus
 ```
 
-### Install
+## Install
 
 ```bash
 yarn
 yarn website:install
 ```
 
-### Build
+## Build
 
 ```bash
 yarn build
 ```
 
-### Test
+## Test
 
 ```bash
 yarn test
@@ -85,7 +91,7 @@ TEST_GREP=natsort yarn test:languages
 This first rewrites mocha test-cases based on `example` and `result` comments found in the function's headers. This is
 useful if you're changing the tests themselves as well.
 
-If that's not needed as you're iterating purely on the implementation, here's a speedier way of singling out `natsort`.
+If that's not needed as you're iterating purely on the implementation, here's a faster way of singeling out `natsort`.
 This re-uses an already generated mocha test:
 
 ```bash
@@ -95,16 +101,16 @@ env DEBUG=locutus:* ./node_modules/.bin/mocha \
 test/languages/php/array/test-natsort.js
 ```
 
-### Website Development
+## Website Development
 
 We keep the website in `./website` so it's easy to keep code and website in sync as we iterate. For those reading this
 screaming murder, [HashiCorp does this](https://github.com/hashicorp/terraform/tree/HEAD/website) for all their
 projects, and it's working well for them on a scale more impressive than ours.
 
 Our website is built with Hexo. To install the prerequisites type `yarn website:install`.
 
-Even the the website is bundled with this repo, we treat it as a separate project, with its own `package.json`. We also
-try to avoid dependencies from the website straight to the main code base. Instead, any such dependency shall be
+Even though the website is bundled with this repo, we treat it as a separate project, with its own `package.json`. We
+also try to avoid dependencies from the website straight to the main code base. Instead, any such dependency shall be
 injected by a script.
 
 Here's the flow that takes written functions to the website:
@@ -113,19 +119,18 @@ Here's the flow that takes written functions to the website:
 - `injectweb` iterates over functions and parses them via the `_load` and `_parse` methods, specifically: the header
   comments that declare authors, tests, and dependencies
 - `injectweb` then writes each function to `website/source`. The code is written as the content. The other parsed
-  properties are prepended as [YAML front matter](https://jekyllrb.com/docs/frontmatter/)
-- Jekyll uses `website/_layouts/function.html` as the layout template for the function collection, this determines how
-  all the properties are rendered.
+  properties are prepended as YAML front matter
 
 Blog posts can be found in `website/source/_posts`.
 
 If you want to preview locally type `yarn website:start`.
 
 Any change to `main` is deployed automatically onto GitHub Pages by CI.
 
-### Releasing
+## Releasing
 
-Any newly pushed git tag is automatically released on NPM by CI. To push a new tag:
+Any newly pushed Git tag is automatically released to NPM by our GHA CI. Core contributors can push a new version and
+tag like so:
 
 ```bash
 npm version patch -m "Release v%s" && git push --tags

README.md

@@ -4,6 +4,12 @@ All your standard libraries will be assimilated into our JavaScript collective.
 
 More info at: https://locutus.io/
 
+## Table of contents
+
+- [Install](#install)
+- [Use](#use)
+- [Development](#development)
+
 ## Install
 
 ```bash
@@ -37,4 +43,3 @@ true
 ## Development
 
 Some guidelines and instructions can be found in [CONTRIBUTING.md](CONTRIBUTING.md)
-

package.json

@@ -36,6 +36,7 @@
     "injectweb": "rimraf website/source/{c,golang,php,python,ruby} && babel-node src/_util/cli.js injectweb",
     "fix:js": "DEBUG=eslint:cli-engine eslint --fix --quiet --ext .js,.jsx,.ts,.tsx .",
     "fix:formatting": "env DEBUG=prettier prettier --write .",
+    "fix:markdown": "remark {README,CONTRIBUTING}.md --output && prettier --write {README,CONTRIBUTING}.md",
     "fix": "npm-run-all --serial 'fix:**'",
     "lint:formatting": "prettier --check .",
     "lint:js": "eslint --ext .js,.jsx,.ts,.tsx .",
@@ -89,6 +90,8 @@
     "npm-run-all": "^4.1.5",
     "prettier": "^3.2.5",
     "prettier-plugin-packagejson": "^2.4.14",
+    "remark-cli": "^11.0.0",
+    "remark-toc": "^8.0.1",
     "rimraf": "3.0.2"
   },
   "packageManager": "yarn@4.0.1+sha224.ca5d6f5a8aecd0801adc32f775675b01961bdc2383867d36f4732a0a",