Refactor docs, make a new website.

* Docs have been migrated from docbook to yaml + jinja2 + pandoc
* Created a new (basic) website for docs based on React + Tailwinds

web/utils/doc-utils.ts

@@ -0,0 +1,73 @@
+import fs from 'fs'
+import path from 'path'
+import yaml from 'js-yaml'
+import { unified } from 'unified'
+import remarkParse from 'remark-parse'
+import remarkGfm from 'remark-gfm'
+import remarkRehype from 'remark-rehype'
+import rehypeStringify from 'rehype-stringify'
+
+const DOC_PATH = path.join(process.cwd(), '..', 'doc')
+
+export interface ConfigSetting {
+  name: string
+  desc: string
+  default: string | undefined
+  args: string[]
+}
+
+export function getConfigSettings(): ConfigSetting[] {
+  const configSettingsFile = fs.readFileSync(
+    path.join(DOC_PATH, 'config_settings.yaml'),
+    'utf-8'
+  )
+  const parsed = yaml.load(configSettingsFile.toString()) as ConfigSetting[]
+  const docs = parsed.map((c) => ({ ...c, desc: processMarkdown(c.desc) }))
+
+  return docs
+}
+
+export interface Variable {
+  name: string
+  desc: string
+  default: string | undefined
+  args: string[]
+}
+
+export function getVariables(): Variable[] {
+  const variablesFile = fs.readFileSync(
+    path.join(DOC_PATH, 'variables.yaml'),
+    'utf-8'
+  )
+  const parsed = yaml.load(variablesFile.toString()) as Variable[]
+  const docs = parsed.map((c) => ({ ...c, desc: processMarkdown(c.desc) }))
+
+  return docs
+}
+
+export interface LuaDoc {
+  name: string
+  desc: string
+  args: string[]
+}
+
+export function getLua(): LuaDoc[] {
+  const variablesFile = fs.readFileSync(
+    path.join(DOC_PATH, 'lua.yaml'),
+    'utf-8'
+  )
+  const parsed = yaml.load(variablesFile.toString()) as LuaDoc[]
+  const docs = parsed.map((c) => ({ ...c, desc: processMarkdown(c.desc) }))
+
+  return docs
+}
+
+function processMarkdown(input: string): string {
+  return unified()
+    .use(remarkParse)
+    .use(remarkGfm)
+    .use(remarkRehype)
+    .use(rehypeStringify)
+    .processSync(input)
+    .toString()
+}

web/utils/mdx-utils.ts

@@ -0,0 +1,96 @@
+import fs from 'fs'
+import path from 'path'
+import matter from 'gray-matter'
+import { serialize } from 'next-mdx-remote/serialize'
+import rehypePrism from '@mapbox/rehype-prism'
+import remarkGfm from 'remark-gfm'
+
+// DOCUMENTS_PATH is useful when you want to get the path to a specific file
+export const DOCUMENTS_PATH = path.join(process.cwd(), 'documents')
+
+// documentFilePaths is the list of all mdx files inside the DOCUMENTS_PATH directory
+export const documentFilePaths = fs
+  .readdirSync(DOCUMENTS_PATH)
+  // Only include md(x) files
+  .filter((path) => /\.mdx?$/.test(path))
+
+export interface Document {
+  content: string
+  data: any
+  filePath: string
+}
+
+export const getDocuments = (): Document[] => {
+  let documents = documentFilePaths.map((filePath) => {
+    const source = fs.readFileSync(path.join(DOCUMENTS_PATH, filePath), 'utf-8')
+    const { content, data } = matter(source)
+
+    return {
+      content,
+      data,
+      filePath,
+    }
+  })
+
+  return documents
+}
+
+export const getDocumentBySlug = async (slug: string) => {
+  const documentFilePath = path.join(DOCUMENTS_PATH, `${slug}.mdx`)
+  const source = fs.readFileSync(documentFilePath, 'utf-8')
+
+  const { content, data } = matter(source)
+
+  const mdxSource = await serialize(content, {
+    // Optionally pass remark/rehype plugins
+    mdxOptions: {
+      remarkPlugins: [remarkGfm],
+      rehypePlugins: [rehypePrism],
+    },
+    scope: data,
+  })
+
+  return { mdxSource, data, documentFilePath }
+}
+
+export const getNextDocumentBySlug = (slug: string) => {
+  const documents = getDocuments()
+  const currentFileName = `${slug}.mdx`
+  const currentDocument = documents.find(
+    (document) => document.filePath === currentFileName
+  )
+  if (!currentDocument) return null
+  const currentDocumentIndex = documents.indexOf(currentDocument)
+
+  const document = documents[currentDocumentIndex - 1]
+  // no prev document found
+  if (!document) return null
+
+  const nextDocumentSlug = document?.filePath.replace(/\.mdx?$/, '')
+
+  return {
+    title: document.data.title,
+    slug: nextDocumentSlug,
+  }
+}
+
+export const getPreviousDocumentBySlug = (slug: string) => {
+  const documents = getDocuments()
+  const currentFileName = `${slug}.mdx`
+  const currentDocument = documents.find(
+    (document) => document.filePath === currentFileName
+  )
+  if (!currentDocument) return null
+  const currentDocumentIndex = documents.indexOf(currentDocument)
+
+  const document = documents[currentDocumentIndex + 1]
+  // no prev document found
+  if (!document) return null
+
+  const previousDocumentSlug = document?.filePath.replace(/\.mdx?$/, '')
+
+  return {
+    title: document.data.title,
+    slug: previousDocumentSlug,
+  }
+}

web/utils/tailwind-preset.js

@@ -0,0 +1,62 @@
+const plugin = require('tailwindcss/plugin')
+const pluginTypography = require('@tailwindcss/typography')
+
+const hoveredSiblingPlugin = plugin(function ({ addVariant, e }) {
+  addVariant('hovered-sibling', ({ container }) => {
+    container.walkRules((rule) => {
+      rule.selector = `:hover + .hovered-sibling\\:${rule.selector.slice(1)}`
+    })
+  })
+})
+
+module.exports = {
+  theme: {
+    fontFamily: {
+      sans: [
+        'Inter',
+        'ui-sans-serif',
+        'system-ui',
+        '-apple-system',
+        'BlinkMacSystemFont',
+        'Segoe UI',
+        'Roboto',
+        'Helvetica Neue',
+        'Arial',
+        'Noto Sans',
+        'sans-serif',
+        'Apple Color Emoji',
+        'Segoe UI Emoji',
+        'Segoe UI Symbol',
+        'Noto Color Emoji',
+      ],
+      serif: [
+        'Inter',
+        'ui-serif',
+        'Georgia',
+        'Cambria',
+        'Times New Roman',
+        'Times',
+        'serif',
+      ],
+      mono: [
+        'Fira Code',
+        'ui-monospace',
+        'SFMono-Regular',
+        'Menlo',
+        'Monaco',
+        'Consolas',
+        'Liberation Mono',
+        'Courier New',
+        'monospace',
+      ],
+    },
+  },
+  variants: {
+    extend: {
+      borderRadius: ['first', 'last'],
+      borderWidth: ['last', 'hovered-sibling'],
+      typography: ['dark'],
+    },
+  },
+  plugins: [hoveredSiblingPlugin, pluginTypography],
+}