Introduce RFC mdBook web page (#60)

- Closes #53
- Preview available [here](https://paritytech.github.io/RFCs/).

![Screenshot 2023-12-19 at 13 55
05](https://github.com/polkadot-fellows/RFCs/assets/12039224/ee06a7ad-231e-4077-a773-c6319661dfb6)


---

### What it does

- The workflow gathers the source markdown files of RFCs - approved
ones, and proposed ones (from open PRs).
- The proposed RFCs are separated into new (<7 days since PR created)
and stale (>30 days since PR updated).
- The RFCs are extended with a table of contents, and a link to the
source.
- The RFCs are build into a web page using
[mdBook](https://github.com/rust-lang/mdBook).
- The built web page gets pushed to `gh-pages` branch - to be published
in Github Pages.
- The workflow is triggered on merge to `main`, and periodically once a
day.

.github/scripts/build-mdbook-summary.js

@@ -0,0 +1,38 @@
+/**
+ * mdBook relies on the creation of a special SUMMARY.md file
+ * https://rust-lang.github.io/mdBook/format/summary.html
+ * This script constructs the summary out of the available source files.
+ */
+
+const fs = require('fs');
+const summaryPath = "mdbook/src/SUMMARY.md"
+
+module.exports = async ({github, context}) => {
+  fs.writeFileSync(summaryPath, "# Summary\n\n[Introduction](introduction.md)\n") // Starting point.
+
+  const appendRfcsToSummary = (dirPath) => {
+    for (const filename of fs.readdirSync(dirPath)) {
+      if (!filename.endsWith(".md")) continue;
+      const filePath = dirPath + filename
+      const text = fs.readFileSync(filePath)
+      const title = text.toString().split(/\n/)
+        .find(line => line.startsWith("# ") || line.startsWith(" # "))
+        .replace("# ", "")
+      // Relative path, without the src prefix (format required by mdbook)
+      const relativePath = filePath.replace("mdbook/src/", "")
+      fs.appendFileSync(summaryPath, `- [${title}](${relativePath})\n`)
+    }
+  }
+
+  fs.appendFileSync(summaryPath, "\n---\n\n# Approved\n\n")
+  appendRfcsToSummary("mdbook/src/approved/")
+
+  fs.appendFileSync(summaryPath, "\n---\n\n# Newly Proposed\n\n")
+  appendRfcsToSummary("mdbook/src/new/")
+
+  fs.appendFileSync(summaryPath, "\n---\n\n# Proposed\n\n")
+  appendRfcsToSummary("mdbook/src/proposed/")
+
+  fs.appendFileSync(summaryPath, "\n---\n\n# Stale\n\n")
+  appendRfcsToSummary("mdbook/src/stale/")
+}

.github/scripts/gather-mdbook-sources.js

@@ -0,0 +1,74 @@
+/**
+ * This scripts gathers source markdown files of approved and proposed RFCS into the mdbook/src directory.
+ */
+
+const fs = require('fs');
+
+// The amount of days that an RFC is considered "new".
+// Counted from the creation of a given PR.
+const NEW_RFC_PERIOD_DAYS = 7
+
+// The amount of days that an RFC is considered "stale".
+// Counted from the last update on a PR.
+const STALE_RFC_PERIOD_DAYS = 30
+
+const dateDaysBefore = (daysBefore) => {
+  const result = new Date()
+  result.setDate(result.getDate() - daysBefore)
+  return result
+}
+
+[
+  "mdbook/src/approved",
+  "mdbook/src/new",
+  "mdbook/src/stale",
+  "mdbook/src/proposed"
+].forEach(path => fs.mkdirSync(path, {resursive: true}))
+
+const TOC = "**Table of Contents**\n\n<\!-- toc -->\n"
+
+module.exports = async ({github, context}) => {
+  const owner = 'polkadot-fellows'
+  const repo = 'RFCs'
+  const prs = await github.paginate(github.rest.pulls.list, {owner, repo, state: 'open'})
+
+  /*
+    The open PRs are potential proposed RFCs.
+    We iterate over them and filter those that include a new RFC markdown file.
+  */
+  for (const pr of prs) {
+    const addedMarkdownFiles = (
+      await github.rest.pulls.listFiles({
+        owner, repo,
+        pull_number: pr.number,
+      })
+    ).data.filter(
+      (file) => file.status === "added" && file.filename.startsWith("text/") && file.filename.includes(".md"),
+    );
+    if (addedMarkdownFiles.length !== 1) continue;
+    const [rfcFile] = addedMarkdownFiles;
+    const rawText = await (await fetch(rfcFile.raw_url)).text();
+
+    const isNew = new Date(pr.created_at) > dateDaysBefore(NEW_RFC_PERIOD_DAYS)
+    const isStale = new Date(pr.updated_at) < dateDaysBefore(STALE_RFC_PERIOD_DAYS)
+    const status = isNew ? 'new' : (isStale ? 'stale' : 'proposed')
+
+    const filename = rfcFile.filename.replace("text/", "")
+
+    fs.writeFileSync(
+      `mdbook/src/${status}/${filename}`,
+      `[(source)](${pr.html_url})\n\n`
+      + TOC
+      + rawText
+    )
+  }
+
+  // Copy the approved (already-merged) RFCs markdown files, first adding a source link at the top and a TOC.
+  for (const file of fs.readdirSync("text/")) {
+    if (!file.endsWith(".md")) continue;
+    const text = `[(source)](https://github.com/polkadot-fellows/RFCs/blob/main/text/${file})\n\n`
+      + TOC
+      + fs.readFileSync(`text/${file}`)
+    fs.writeFileSync(`mdbook/src/approved/${file}`, text)
+  }
+}

.github/workflows/mdbook.yml

@@ -0,0 +1,49 @@
+name: mdBook
+
+on:
+  push:
+    branches:
+      - main
+  schedule:
+    - cron: "0 0 * * *" # Once a day
+
+jobs:
+  mdbook:
+    runs-on: ubuntu-latest
+    permissions:
+      # For writing to gh-pages branch.
+      contents: write
+    steps:
+      - name: Checkout this repo
+        uses: actions/checkout@v3
+        # Gather mdbook source files - approved (merged) files, and open PRs.
+      - name: Gather mdbook sources
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const script = require('.github/scripts/gather-mdbook-sources.js')
+            await script({github, context})
+      - name: Build the mdbook SUMMARY.md
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const script = require('.github/scripts/build-mdbook-summary.js')
+            await script({github, context})
+      - name: Setup mdBook binary
+        uses: peaceiris/actions-mdbook@adeb05db28a0c0004681db83893d56c0388ea9ea # v1.2.0
+        with:
+          mdbook-version: '0.4.36'
+      - name: Install dependencies
+        run: |
+          cargo install mdbook-toc@0.14.1
+      - name: Generate the mdbook
+        run: |
+          cd mdbook
+          rm -rf ./book/
+          mdbook build --dest-dir ./book/
+
+      - name: Deploy to github pages
+        uses: peaceiris/actions-gh-pages@373f7f263a76c20808c831209c920827a82a2847 # v3.9.3
+        with:
+          publish_dir: ./mdbook/book
+          github_token: ${{ secrets.GITHUB_TOKEN }}

mdbook/.gitignore

@@ -0,0 +1,11 @@
+# Autogenerated
+book/
+
+# Generated by the `build-mdbook-summary` script
+SUMMARY.md
+
+# Generated by the `gather-mdbook-sources` script
+src/approved/
+src/new/
+src/proposed/
+src/stale/

mdbook/README.md

@@ -0,0 +1,8 @@
+# RFCs book
+
+An mdbook-based web page for presenting approved and proposed RFCs.
+
+## Prerequisites
+
+- [mdbook](https://github.com/rust-lang/mdBook)
+- [mdbook-toc](https://github.com/badboy/mdbook-toc)

mdbook/book.toml

@@ -0,0 +1,23 @@
+[book]
+title = "Polkadot Fellowship RFCs"
+description = "An online book of RFCs approved or proposed within the Polkadot Fellowship."
+src = "src"
+
+[build]
+create-missing = false
+
+[output.html]
+additional-css = ["theme/polkadot.css"]
+default-theme = "polkadot"
+preferred-dark-theme = "polkadot"
+copy-fonts = true
+no-section-label = true
+
+[output.html.font]
+enable = true
+woff = true
+
+[preprocessor.toc]
+command = "mdbook-toc"
+renderer = ["html"]
+max-level = 3

mdbook/src/introduction.md

@@ -0,0 +1,8 @@
+<p><img width="30%" src="images/Polkadot_Logo_Horizontal_Pink_Black.svg" alt="Polkadot logo" /></p>
+
+# Introduction
+
+This book contains the Polkadot Fellowship Requests for Comments (RFCs)
+detailing proposed changes to the technical implementation of the Polkadot network.
+
+<p><img width="2%" src="images/github-mark.svg" alt="GitHub logo" />&nbsp;<a href="https://github.com/polkadot-fellows/RFCs/">polkadot-fellows/RFCs</a></p>

mdbook/theme/fonts/fonts.css

@@ -0,0 +1,42 @@
+@font-face {
+  font-family:Unbounded;
+  src:url(./Unbounded-ExtraLight.woff2) format("woff2");
+  font-weight:200;
+  font-style:normal;
+  font-display:block
+}
+@font-face {
+  font-family:Unbounded;
+  src:url(./Unbounded-Light.woff2) format("woff2");
+  font-weight:300;
+  font-style:normal;
+  font-display:block
+}
+@font-face {
+  font-family:Unbounded;
+  src:url(./Unbounded-Regular.woff2) format("woff2");
+  font-weight:400;
+  font-style:normal;
+  font-display:block
+}
+@font-face {
+  font-family:Unbounded;
+  src:url(./Unbounded-Medium.woff2) format("woff2");
+  font-weight:500;
+  font-style:normal;
+  font-display:block
+}
+@font-face {
+  font-family:Unbounded;
+  src:url(./Unbounded-Bold.woff2) format("woff2");
+  font-weight:700;
+  font-style:normal;
+  font-display:block
+}
+@font-face {
+  font-family:Unbounded;
+  src:url(./Unbounded-Black.woff2) format("woff2");
+  font-weight:900;
+  font-style:normal;
+  font-display:block
+}