docs: Website migration from docusaurus to vitepress (#45)

## Description This PR fully migrates to vitepress usage for docs website generation * moving most files to .md format * migration to vitepress * reorganize the docs structure * implement stylistic design for home page * adding astria-go-cli "walk through" * using npm instead of yarn ## Motivation and Context The docs design and structure need a new styling and home page, vitepress was chosen considering needs. ## Screenshots (if appropriate): ![image](https://github.com/astriaorg/docs/assets/121364949/1c13df71-f933-4729-9001-4578dcb4d041) ## Types of changes - [x] Edits to existing documentation - [x] Changing documentation structure (relocating existing files, ensure redirects exist) - [x] Stylistic changes (provide screenshots above) --------- Co-authored-by: Josh Bowen <[email protected]>
astriaorg · Apr 15, 2024 · 17a2d7e · 17a2d7e
1 parent 3895bea
commit 17a2d7e
Show file tree

Hide file tree

Showing 44 changed files with 21,846 additions and 1,173 deletions.
diff --git a/.eslintrc.js b/.eslintrc.js
@@ -24,15 +24,13 @@ module.exports = {
       extends: ['plugin:markdownlint/recommended'],
       rules: {
         'markdownlint/md001': "off",
-        'markdownlint/md013': [ 'error', {
-          code_block_line_length: 120,
-          tables: false
-        }],
-        'markdownlint/md024': [ 'error', {
-            allow_different_nesting: true
-          }
+        'markdownlint/md013': "off",
+        'markdownlint/md024': ['error', {
+          allow_different_nesting: true
+        }
         ],
         'markdownlint/md032': "off",
+        'markdownlint/md041': "off",
       }
     },
   ],

diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
@@ -1,43 +1,62 @@
-name: Deploy to GitHub Pages
+# Sample workflow for building and deploying a VitePress site to GitHub Pages
+#
+name: Deploy VitePress site to Pages
 
 on:
+  # Runs on pushes targeting the `main` branch. Change this to `master` if you're
+  # using the `master` branch as the default branch.
   push:
-    branches:
-      - main
-    # Review gh actions docs if you want to further define triggers, paths, etc
-    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on
+    branches: [main]
 
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:
-  contents: write
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: pages
+  cancel-in-progress: false
 
 jobs:
-  deploy:
-    name: Deploy to GitHub Pages
+  # Build job
+  build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-node@v3
+      - name: Checkout
+        uses: actions/checkout@v4
         with:
-          node-version: 18
-          cache: yarn
-
+          fetch-depth: 0 # Not needed if lastUpdated is not enabled
+      # - uses: pnpm/action-setup@v3 # Uncomment this if you're using pnpm
+      # - uses: oven-sh/setup-bun@v1 # Uncomment this if you're using Bun
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm # or pnpm / yarn
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
       - name: Install dependencies
-        run: yarn install --frozen-lockfile
-      - name: Build website
-        run: yarn build
-
-      # Popular action to deploy to GitHub Pages:
+        run: npm ci # or pnpm install / yarn install / bun install
+      - name: Build with VitePress
+        run: npm run docs:build # or pnpm docs:build / yarn docs:build / bun run docs:build
+              # Popular action to deploy to GitHub Pages:
       # Docs: https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-docusaurus
       - name: Deploy to GitHub Pages
         uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           # Build output to publish to the `gh-pages` branch:
-          publish_dir: ./build
+          publish_dir: ./docs/.vitepress/dist
           # The following lines assign commit authorship to the official
           # GH-Actions bot for deploys to `gh-pages` branch:
           # https://github.com/actions/checkout/issues/13#issuecomment-724415212
           # The GH actions bot is used by default if you didn't specify the two fields.
           # You can swap them out with your own user credentials.
           user_name: github-actions[bot]
-          user_email: 41898282+github-actions[bot]@users.noreply.github.com
+          user_email: 41898282+github-actions[bot]@users.noreply.github.com
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
@@ -8,12 +8,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
-      - uses: actions/setup-node@v3
+      - uses: actions/setup-node@v3.3.0
         with:
           node-version: 18
-          cache: yarn
+          cache: npm
 
       - name: Install dependencies
-        run: yarn install --frozen-lockfile
+        run: npm ci
       - name: Lint
-        run: yarn run lint
+        run: npm run lint
diff --git a/.github/workflows/test-deploy.yml b/.github/workflows/test-deploy.yml
@@ -11,12 +11,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
-      - uses: actions/setup-node@v3
+      - uses: actions/setup-node@v3.3.0
         with:
           node-version: 18
-          cache: yarn
+          cache: npm
 
       - name: Install dependencies
-        run: yarn install --frozen-lockfile
+        run: npm ci
       - name: Test build website
-        run: yarn build
+        run: npm run docs:build
diff --git a/.gitignore b/.gitignore
@@ -25,5 +25,7 @@ yarn-error.log*
 .idea/
 .vscode/
 
-# we use yarn.lock
-package-lock.json
+
+# vitepress builds
+docs/.vitepress/dist
+docs/.vitepress/cache
diff --git a/README.md b/README.md
@@ -1,45 +1,39 @@
 # Astria Docs
 
-The Astria Docs website is built using [Docusaurus 2](https://docusaurus.io/).
+The Astria Docs website built with [VitePress](https://vitepress.dev/)
 
 ### Installation
 
 ```
-$ yarn
+npm add -D vitepress
 ```
 
 ### Local Development
 
 ```
-$ yarn start
+npm run docs:dev
 ```
 
-This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+This command starts a local development server. Most changes are reflected live without having to restart the server.
+
 
 ### Build
 
 ```
-$ yarn build
+npm run docs:build
 ```
 
+
 This command generates static content into the `build` directory and can be served using any static contents hosting service.
 
 ### Deployment
 
-The main astria docs website is deployed using the [github deploy action](.github/workflows/deploy.yml).
-
-To deploy manually:
-
-Using SSH:
-
 ```
-$ USE_SSH=true yarn deploy
+npm run docs:preview
 ```
 
-Not using SSH:
+This command starts a local server from the static content generated above for preview before deployment.
 
-```
-$ GIT_USER=<Your GitHub username> yarn deploy
-```
+The main astria docs website is deployed using the [github deploy action](.github/workflows/deploy.yml).
 
 If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -0,0 +1,124 @@
+import { defineConfig } from 'vitepress'
+const { BASE: base = "/" } = process.env;
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: "Astria",
+  description: "The Shared Sequencer Network",
+  lastUpdated: true,
+  cleanUrls: true,
+  ignoreDeadLinks: true,
+  base: base,
+  themeConfig: {
+    editLink: {
+      pattern: "https://github.com/astriaorg/docs/edit/main/docs/:path",
+      text: "Edit this page on GitHub",
+    },
+
+    logo: { src: '/astria-logo-mini.svg', width: 24, height: 24 },
+
+    // https://vitepress.dev/reference/default-theme-config
+    nav: nav(),
+
+    search: {
+      provider: "local",
+      options: {
+        detailedView: true,
+      },
+    },
+
+    sidebar: sidebar(),
+
+    socialLinks: [
+      { icon: "github", link: "https://github.com/astriaorg" },
+      { icon: "twitter", link: "https://twitter.com/AstriaOrg" },
+    ],
+  }
+})
+
+function sidebar() {
+  return [
+    {
+
+      items: [
+        {
+          text: 'What is Astria?',
+          collapsed: true,
+          items: [
+            { text: 'Overview', link: '/overview/1-introduction' },
+            { text: 'Why Decentralized Sequencers?', link: '/overview/2-why-decentralized-sequencers' },
+            { text: 'Cross-Rollup Composability', link: '/overview/3-cross-rollup-composability' },
+
+            {
+              text: 'Architecture',
+              collapsed: true,
+              items: [
+                { text: 'Overview', link: '/overview/architecture/1-overview' },
+                { text: 'Transaction Flow', link: '/overview/architecture/2-transaction-flow' },
+                { text: 'Rollups', link: '/overview/architecture/3-rollup' },
+                { text: 'Composer', link: '/overview/architecture/4-composer' },
+                { text: 'The Astria Sequencer', link: '/overview/architecture/5-the-astria-sequencer' },
+                { text: 'Relayer', link: '/overview/architecture/6-relayer' },
+                { text: 'Conductor', link: '/overview/architecture/7-conductor' },
+                { text: 'Data Availability Layer', link: '/overview/architecture/8-data-availability-layer' },
+              ]
+            },
+          ]
+        }
+      ],
+    },
+    {
+      text: 'Developers',
+      collapsed: true,
+      items: [
+        {
+          text: 'Tutorials',
+          collapsed: true,
+          items: [
+            { text: 'Deploy a Local Rollup', link: '/local-rollup/1-introduction' },
+            {
+              text: 'Deploy a Cloud Rollup',
+              collapsed: true,
+              items: [
+                { text: 'Digital Ocean', link: '/cloud-rollup/digital-ocean' },
+              ]
+            },
+            { text: 'Using the astria cli', link: '/developer/tutorials/1-using-astria-go-cli.md' },
+
+          ]
+        },
+        {
+          text: 'The Astria EVM', link: '/astria-evm/overview'
+        },
+      ]
+    },
+    {
+      text: 'Resources',
+      collapsed: true,
+      items: [
+        {
+          text: 'Community',
+          collapsed: true,
+          items: [
+            { text: 'Overview', link: '/community/1-overview' }
+          ]
+        },
+        { text: 'Dusknet FAQ', link: '/dusk-faq/1-information' }
+      ]
+    }
+  ]
+}
+
+function nav() {
+  return [
+    { text: 'Home', link: '/' },
+    {
+      text: "Join the network",
+      items: [
+        { text: "Learn", link: "/overview/1-introduction" },
+        { text: "Developers", link: "/local-rollup/1-introduction" },
+        { text: "Community", link: '/community/1-overview' },
+      ],
+    },
+  ];
+}
diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts
@@ -0,0 +1,17 @@
+// https://vitepress.dev/guide/custom-theme
+import { h } from 'vue'
+import type { Theme } from 'vitepress'
+import DefaultTheme from 'vitepress/theme'
+import './style.css'
+
+export default {
+  extends: DefaultTheme,
+  Layout: () => {
+    return h(DefaultTheme.Layout, null, {
+      // https://vitepress.dev/guide/extending-default-theme#layout-slots
+    })
+  },
+  enhanceApp({ app, router, siteData }) {
+    // ...
+  }
+} satisfies Theme