Replace Category with Kind

kazk · kazk · commit c5d6830ce343 · 2020-07-14T19:46:06.000-07:00
Category was meant to describe different document types, but it was confusing and
can be mistaken as category within our docs (i.e., topics).
Kind should be a better name for the intention and we're going to add a new type
Topic to describe the main subject of the document.
diff --git a/README.md b/README.md
@@ -6,22 +6,26 @@
 
 Documents are classified with the following:
 
-- `Category` (`category`): Document belongs to a category
-- `Tag` (`tags`): Document can have multiple tags
+- `Kind` (`kind`): By kind of documentation (`recipe`, `reference`, `tutorial`, etc.) See [kinds.yml].
+- `Tag` (`tags`): By tags associated with the documentation. See [tags.yml].
 - `Language` (`languages`): A special kind of `Tag` that is used to collect documents to show on the language page
 
 ## Routes
 
+- `/tutorials/`: All docs with kind `tutorial`
+- `/recipes/`: All docs with kind `recipe`
+- `/references/`: All docs with kind `reference`
+- `/tags/`: List of all tags
+- `/tags/:id`: List of docs with tag `id`
 - `/languages/`: List of supported languages
 - `/languages/:id`: Show language information
-  - Sidebar lists all pages referencing the language, grouped by `category`
-- `/tags/`: List of tags
-- `/tags/:id`: List of pages with tag `id`
-- `/categories/`: List of documentation categories
-- `/categories/:id`: List of pages in the category
+  - Sidebar lists all pages referencing the language, grouped by `kind`
 
 Markdown files matching `content/**/*.md` generates matching routes. For example, `content/foo/bar.md` generates `/foo/bar/`.
 
 ---
 
 Built with [Gridsome](https://gridsome.org/) using [docc](https://github.com/mrcrmn/docc) starter.
+
+[kinds.yml]: ./data/kinds.yml
+[tags.yml]: ./data/tags.yml
diff --git a/content/docs/deploying.md b/content/docs/deploying.md
@@ -1,6 +1,6 @@
 ---
 description: ""
-category: docs
+kind: reference
 sidebar: "docs"
 prev: "/docs/writing-content/"
 next: "/docs/settings/"
diff --git a/content/docs/index.md b/content/docs/index.md
@@ -1,6 +1,6 @@
 ---
 description: ""
-category: docs
+kind: reference
 sidebar: "docs"
 next: "/docs/installation/"
 tags:
diff --git a/content/docs/installation.md b/content/docs/installation.md
@@ -1,6 +1,6 @@
 ---
 description: ""
-category: docs
+kind: reference
 sidebar: "docs"
 prev: "/docs/"
 next: "/docs/writing-content/"
diff --git a/content/docs/settings.md b/content/docs/settings.md
@@ -1,6 +1,6 @@
 ---
 description: ""
-category: docs
+kind: reference
 sidebar: "docs"
 prev: "/docs/deploying/"
 next: "/docs/sidebar/"
diff --git a/content/docs/sidebar.md b/content/docs/sidebar.md
@@ -1,6 +1,6 @@
 ---
 description: ""
-category: docs
+kind: reference
 sidebar: "docs"
 prev: "/docs/settings/"
 tags:
diff --git a/content/docs/writing-content.md b/content/docs/writing-content.md
@@ -1,6 +1,6 @@
 ---
 description: ""
-category: docs
+kind: reference
 sidebar: "docs"
 prev: "/docs/installation/"
 next: "/docs/settings/"
diff --git a/content/languages/javascript/testing.md b/content/languages/javascript/testing.md
@@ -1,5 +1,5 @@
 ---
-category: guides
+kind: recipe
 tags:
   - testing
 languages:
diff --git a/content/languages/python/codewars-test-famework/index.md b/content/languages/python/codewars-test-famework/index.md
@@ -1,5 +1,5 @@
 ---
-category: references
+kind: reference
 languages: [python]
 tags:
   - testing
diff --git a/content/references/javascript-ref.md b/content/references/javascript-ref.md
@@ -1,5 +1,5 @@
 ---
-category: references
+kind: reference
 languages: [javascript]
 sidebar: "language:javascript"
 prev: /languages/javascript/
@@ -9,4 +9,4 @@ prev: /languages/javascript/
 
 > TODO Remove this file
 
-This file exists to show how the sidebar on language pages are automatically populated and grouped by `category`.
+This file exists to show how the sidebar on language pages are automatically populated and grouped by `kind`.
diff --git a/data/categories.yml b/data/categories.yml
diff --git a/data/kinds.yml b/data/kinds.yml
@@ -0,0 +1,36 @@
+# Fields
+# id: Must be unique. Used in URLs. Singular.
+# name: Display name. Capitalized plural for now.
+# description: Short description of the kind. Currently not used.
+# path: Required to create an index page and show on home.
+
+# Main 4 kinds taken from https://documentation.divio.com
+
+# keywords: lesson, newcomer, get started
+- id: tutorial
+  name: Tutorials
+  description: ""
+  path: /tutorials/
+
+# keywords: how to, problem oriented, one goal
+- id: recipe
+  name: Recipes
+  description: ""
+  path: /recipes/
+
+# keywords: describe, list, brief
+- id: reference
+  name: References
+  description: ""
+  path: /references/
+
+# keywords: explain, why, concepts, background, discussion, further reading
+- id: explanation
+  name: Explanations
+  description: ""
+
+# Similar to Recipes, but focused on providing a copy pastable code.
+# Recipes can link to these to provide alternative solutions.
+- id: snippet
+  name: Snippets
+  description: ""
diff --git a/gridsome.config.js b/gridsome.config.js
@@ -70,9 +70,9 @@ module.exports = {
           plugins: ["@gridsome/remark-prismjs"],
         },
         refs: {
-          // Each page is classified under a single category.
-          category: {
-            typeName: "Category",
+          // Each documentation should belong to a single kind.
+          kind: {
+            typeName: "Kind",
           },
           // Can have multiple tags.
           tags: {
@@ -107,12 +107,6 @@ module.exports = {
   },
 
   templates: {
-    Category: [
-      {
-        path: "/categories/:id/",
-        component: "@/templates/Category.vue",
-      },
-    ],
     Tag: [
       {
         path: "/tags/:id/",
diff --git a/gridsome.server.js b/gridsome.server.js
@@ -58,13 +58,18 @@ module.exports = function (api) {
   const addNodesFromFile = async (collection, file, fn = (x) => x) => {
     const contents = await readFile(file, { encoding: "utf-8" });
     const items = YAML.parse(contents);
-    for (const item of items) collection.addNode(fn(item));
+    for (let i = 0; i < items.length; ++i) collection.addNode(fn(items[i], i));
   };
 
   api.loadSource(async ({ addCollection, addSchemaTypes }) => {
     await addNodesFromFile(
-      addCollection("Category"),
-      path.join(__dirname, "data/categories.yml")
+      addCollection("Kind"),
+      path.join(__dirname, "data/kinds.yml"),
+      (kind, i) => {
+        // Add position so that it can be shown in the order declared.
+        kind.position = i;
+        return kind;
+      }
     );
     await addNodesFromFile(
       addCollection("Tag"),
@@ -89,7 +94,31 @@ module.exports = function (api) {
     );
   });
 
-  api.createPages(({ createPage }) => {
+  api.createPages(async ({ createPage, graphql, findPages }) => {
     // Use the Pages API here: https://gridsome.org/docs/pages-api/
+    const { data } = await graphql(`
+      {
+        kinds: allKind {
+          edges {
+            node {
+              id
+              path
+            }
+          }
+        }
+      }
+    `);
+
+    data.kinds.edges.forEach(({ node }) => {
+      // Couldn't figure out proper filter `filter: { path: { nin: ["", null] } }` returns nodes with null path
+      if (!node.path) return;
+      createPage({
+        path: node.path,
+        component: "./src/templates/KindT.vue",
+        context: {
+          id: node.id,
+        },
+      });
+    });
   });
 };
diff --git a/src/layouts/Default.vue b/src/layouts/Default.vue
@@ -71,7 +71,7 @@ query {
         languages {
           id
         }
-        category {
+        kind {
           id
           name
         }
@@ -129,7 +129,7 @@ export default {
 
       const groups = {};
       for (const p of pages) {
-        const key = p.category.name;
+        const key = p.kind.name;
         if (!groups[key]) groups[key] = [];
         groups[key].push(p);
       }
diff --git a/src/pages/Categories.vue b/src/pages/Categories.vue
diff --git a/src/pages/Index.vue b/src/pages/Index.vue
diff --git a/src/templates/KindT.vue b/src/templates/KindT.vue
diff --git a/src/templates/MarkdownPage.vue b/src/templates/MarkdownPage.vue
diff --git a/src/templates/Tag.vue b/src/templates/Tag.vue
