Skip to content

Commit

Permalink
docs: Website migration from docusaurus to vitepress (#45)
Browse files Browse the repository at this point in the history
## 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]>
  • Loading branch information
quasystaty1 and jbowen93 authored Apr 15, 2024
1 parent 3895bea commit 17a2d7e
Show file tree
Hide file tree
Showing 44 changed files with 21,846 additions and 1,173 deletions.
12 changes: 5 additions & 7 deletions .eslintrc.js
Original file line number Diff line number Diff line change
Expand Up @@ -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",
}
},
],
Expand Down
59 changes: 39 additions & 20 deletions .github/workflows/deploy.yml
Original file line number Diff line number Diff line change
@@ -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
8 changes: 4 additions & 4 deletions .github/workflows/lint.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
8 changes: 4 additions & 4 deletions .github/workflows/test-deploy.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
6 changes: 4 additions & 2 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -25,5 +25,7 @@ yarn-error.log*
.idea/
.vscode/

# we use yarn.lock
package-lock.json

# vitepress builds
docs/.vitepress/dist
docs/.vitepress/cache
26 changes: 10 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
@@ -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.
124 changes: 124 additions & 0 deletions docs/.vitepress/config.mts
Original file line number Diff line number Diff line change
@@ -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' },
],
},
];
}
17 changes: 17 additions & 0 deletions docs/.vitepress/theme/index.ts
Original file line number Diff line number Diff line change
@@ -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
Loading

0 comments on commit 17a2d7e

Please sign in to comment.