Improve docs (#450)

- update docusaurus
- add typescript
- add prettier
- add open-collective & sponsor us links
- add announcement bar (star on github)
- add mastodon (footer)
- collapse admin area in sidebar by default
- move faq doc to pages

.github/ISSUE_TEMPLATE/config.yml

@@ -4,5 +4,5 @@ contact_links:
     url: https://discord.gg/fcMQqSMXJy
     about: Ask questions and discuss with other Woodpecker users.
   - name: Frequently Asked Questions
-    url: https://woodpecker-ci.org/docs/faq
+    url: https://woodpecker-ci.org/faq
     about: Check the FAQs for common questions.

docs/.prettierrc.js

@@ -0,0 +1,8 @@
+module.exports = {
+  semi: true,
+  trailingComma: "all",
+  singleQuote: true,
+  printWidth: 120,
+  tabWidth: 2,
+  endOfLine: "lf",
+};

docs/docs/30-administration/_category_.yml

@@ -1,4 +1,4 @@
 label: 'Administration'
 # position: 3
 collapsible: true
-collapsed: false
+collapsed: true

docs/docusaurus.config.js

@@ -1,5 +1,6 @@
 const lightCodeTheme = require('prism-react-renderer/themes/github');
 const darkCodeTheme = require('prism-react-renderer/themes/dracula');
+const path = require('path');
 
 /** @type {import('@docusaurus/types').DocusaurusConfig} */
 module.exports = {
@@ -8,7 +9,8 @@ module.exports = {
   url: 'https://woodpecker-ci.org',
   baseUrl: '/',
   onBrokenLinks: 'throw',
-  onBrokenMarkdownLinks: 'warn',
+  onBrokenMarkdownLinks: 'throw',
+  onDuplicateRoutes: 'throw',
   favicon: 'img/favicon.ico',
   organizationName: 'woodpecker-ci',
   projectName: 'woodpecker-ci.github.io',
@@ -28,23 +30,27 @@ module.exports = {
           position: 'left',
           label: 'Docs',
         },
-        {
-          type: 'doc',
-          docId: 'faq',
-          position: 'left',
-          label: 'FAQ',
-        },
         {
           type: 'doc',
           docId: 'migrations',
           position: 'left',
           label: 'Migrations',
         },
-        // {to: '/blog', label: 'Blog', position: 'left'},
+        {
+          to: '/faq',
+          position: 'left',
+          label: 'FAQ',
+        },
         {
           href: 'https://github.com/woodpecker-ci/woodpecker',
-          label: 'GitHub',
           position: 'right',
+          className: 'header-github-link',
+          'aria-label': 'GitHub repository',
+        },
+        {
+          label: '🧡 Sponsor Us',
+          position: 'right',
+          href: 'https://opencollective.com/woodpecker-ci',
         },
       ],
     },
@@ -64,7 +70,7 @@ module.exports = {
             },
             {
               label: 'FAQ',
-              to: '/docs/faq',
+              to: '/faq',
             },
           ],
         },
@@ -75,15 +81,15 @@ module.exports = {
               label: 'Discord',
               href: 'https://discord.gg/fcMQqSMXJy',
             },
+            {
+              label: 'Mastodon',
+              href: 'https://mastodon.technology/@WoodpeckerCI',
+            },
           ],
         },
         {
           title: 'More',
           items: [
-            // {
-            //   label: 'Blog',
-            //   to: '/blog',
-            // },
             {
               label: 'GitHub',
               href: 'https://github.com/woodpecker-ci/woodpecker',
@@ -101,10 +107,16 @@ module.exports = {
       theme: lightCodeTheme,
       darkTheme: darkCodeTheme,
     },
+    announcementBar: {
+      id: 'github-star',
+      content: ` If you like Woodpecker-CI, <a href=https://github.com/woodpecker-ci/woodpecker rel="noopener noreferrer" target="_blank">give us a star on GitHub</a> ! ⭐️`,
+      backgroundColor: 'var(--ifm-color-primary)',
+      textColor: 'var(--ifm-color-gray-900)',
+    },
     algolia: {
-      appId: "BH4D9OD16A",
+      appId: 'BH4D9OD16A',
-      apiKey: "148f85e216b68d20ffa49d46a2b89d0e",
+      apiKey: '148f85e216b68d20ffa49d46a2b89d0e',
-      indexName: "woodpecker-ci",
+      indexName: 'woodpecker-ci',
       debug: false, // Set debug to true if you want to inspect the modal
     },
   },
@@ -116,10 +128,6 @@ module.exports = {
           sidebarPath: require.resolve('./sidebars.js'),
           editUrl: 'https://github.com/woodpecker-ci/woodpecker/edit/master/docs/',
         },
-        // blog: {
-        //   showReadingTime: true,
-        //   editUrl: 'https://github.com/woodpecker-ci/woodpecker/edit/master/docs/blog/',
-        // },
         theme: {
           customCss: require.resolve('./src/css/custom.css'),
         },

docs/package.json

@@ -14,9 +14,9 @@
     "write-heading-ids": "docusaurus write-heading-ids"
   },
   "dependencies": {
-    "@docusaurus/core": "2.0.0-beta.6",
+    "@docusaurus/core": "^2.0.0-beta.7",
-    "@docusaurus/preset-classic": "2.0.0-beta.6",
+    "@docusaurus/preset-classic": "^2.0.0-beta.7",
-    "@docusaurus/theme-search-algolia": "^2.0.0-beta.6",
+    "@docusaurus/theme-search-algolia": "^2.0.0-beta.7",
     "@mdx-js/react": "^1.6.22",
     "@svgr/webpack": "^5.5.0",
     "clsx": "^1.1.1",
@@ -37,5 +37,13 @@
       "last 1 firefox version",
       "last 1 safari version"
     ]
+  },
+  "devDependencies": {
+    "@docusaurus/module-type-aliases": "^2.0.0-beta.7",
+    "@tsconfig/docusaurus": "^1.0.4",
+    "@types/react": "^17.0.30",
+    "@types/react-helmet": "^6.1.4",
+    "@types/react-router-dom": "^5.3.1",
+    "typescript": "^4.4.4"
   }
 }

docs/src/css/custom.css

@@ -26,3 +26,21 @@
 html[data-theme='dark'] .docusaurus-highlight-code-line {
   background-color: rgba(0, 0, 0, 0.3);
 }
+
+.header-github-link:hover {
+  opacity: 0.6;
+}
+
+.header-github-link:before {
+  content: '';
+  width: 24px;
+  height: 24px;
+  display: flex;
+  background: url("data:image/svg+xml,%3Csvg viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12'/%3E%3C/svg%3E")
+    no-repeat;
+}
+
+html[data-theme='dark'] .header-github-link:before {
+  background: url("data:image/svg+xml,%3Csvg viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath fill='white' d='M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12'/%3E%3C/svg%3E")
+    no-repeat;
+}

docs/src/pages/faq.md

@@ -6,6 +6,7 @@ Apart from Woodpecker staying free and OpenSource forever, the growing community
 - [Multi pipelines](/docs/usage/multi-pipeline)
 - [Conditional step execution on file changes](/docs/usage/pipeline-syntax#path)
 - [More features are already in the pipeline :wink:](https://github.com/woodpecker-ci/woodpecker/pulls) ...
+
 ## Why is Woodpecker a fork of Drone version 0.8?
 
 The Drone CI license was changed after the 0.8 release from Apache 2 to a proprietary license. Woodpecker is based on this latest freely available version.

docs/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "@tsconfig/docusaurus/tsconfig.json",
+  "include": ["src/"]
+}