Skip to content

Commit

Permalink
chore: migrate to docusaurus
Browse files Browse the repository at this point in the history
  • Loading branch information
jeluard committed Mar 12, 2024
1 parent 35aec8f commit 41a8a35
Show file tree
Hide file tree
Showing 30 changed files with 9,706 additions and 115 deletions.
10 changes: 2 additions & 8 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -64,19 +64,13 @@ jobs:

- name: Set up Python
uses: actions/setup-python@v1

- name: Install dependencies
working-directory: docs
run: |
python -m pip install --upgrade pip
pip install -r requirements.txt

- name: Build docs
working-directory: docs
run: mkdocs build --verbose --clean --site-dir site
run: yarn && yarn build

- name: Deploy
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./docs/site
publish_dir: ./docs/build
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -77,3 +77,7 @@ packages/cli/.git-data.json
dictionary.dic

temp/

# Docusaurus
.docusaurus
build/
3 changes: 3 additions & 0 deletions .wordlist.txt
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ DVs
Discv
DockerHub
Dockerized
Docusaurus
EIP
EIPs
EL
Expand All @@ -39,6 +40,7 @@ Geth
Github
Gossipsub
Grafana
HTTPS
HackMD
Homebrew
IPFS
Expand Down Expand Up @@ -91,6 +93,7 @@ api
async
backfill
beaconcha
blockRoot
blockchain
bootnode
bootnodes
Expand Down
25 changes: 25 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# Website

This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.

### Installation

```
$ yarn
```

### Local Development

```
$ yarn start
```

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

### Build

```
$ yarn build
```

This command generates static content into the `build` directory and can be served using any static contents hosting service.
3 changes: 3 additions & 0 deletions docs/babel.config.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
module.exports = {
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
};
111 changes: 111 additions & 0 deletions docs/docusaurus.config.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,111 @@
// @ts-check
// `@type` JSDoc annotations allow editor autocompletion and type checking
// (when paired with `@ts-check`).
// There are various equivalent ways to declare your Docusaurus config.
// See: https://docusaurus.io/docs/api/docusaurus-config

import {themes as prismThemes} from "prism-react-renderer";

/** @type {import('@docusaurus/types').Config} */
const config = {
title: "Lodestar",
tagline: "TypeScript Implementation of Ethereum Consensus",
favicon: "img/favicon.ico",

// Set the production url of your site here
url: "https://chainsafe.github.io/",
// Set the /<baseUrl>/ pathname under which your site is served
// For GitHub pages deployment, it is often '/<projectName>/'
baseUrl: "/lodestar/",

// GitHub pages deployment config.
organizationName: "ChainSafe",
projectName: "lodestar",

onBrokenLinks: "warn",
onBrokenMarkdownLinks: "warn",

i18n: {
defaultLocale: "en",
locales: ["en"],
},

presets: [
[
"classic",
/** @type {import('@docusaurus/preset-classic').Options} */
({
docs: {
path: "pages",
sidebarPath: "./sidebars.js",
editUrl: "https://github.com/ChainSafe/lodestar/tree/unstable/docs/",
routeBasePath: "/",
},
theme: {
customCss: "./src/css/custom.css",
},
}),
],
],

markdown: {
mermaid: true,
},
themes: [
'@docusaurus/theme-mermaid',
'@easyops-cn/docusaurus-search-local'
],

themeConfig:
/** @type {import('@docusaurus/preset-classic').ThemeConfig} */
({
navbar: {
title: "Lodestar Documentation",
logo: {
alt: "Lodestar Logo",
src: "img/logo.png",
},
items: [
{
href: "https://github.com/ChainSafe/lodestar",
label: "GitHub",
position: "right",
},
],
},
footer: {
style: "dark",
links: [
{
title: "Docs",
items: [
{
label: "Introduction",
to: "/introduction",
},
],
},
{
title: "Community",
items: [
{
label: "Discord",
href: "https://discord.com/invite/yjyvFRP",
},
{
label: "Twitter",
href: "https://twitter.com/lodestar_eth",
},
],
},
],
copyright: `Copyright © ${new Date().getFullYear()} ChainSafe, Inc.`,
},
prism: {
theme: prismThemes.github,
darkTheme: prismThemes.dracula,
},
}),
};

export default config;
Binary file removed docs/images/favicon.ico
Binary file not shown.
46 changes: 46 additions & 0 deletions docs/package.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
{
"name": "@lodestar/docs",
"version": "0.0.0",
"private": true,
"scripts": {
"docusaurus": "docusaurus",
"start": "docusaurus start",
"build": "docusaurus build",
"swizzle": "docusaurus swizzle",
"deploy": "docusaurus deploy",
"clear": "docusaurus clear",
"serve": "docusaurus serve",
"write-translations": "docusaurus write-translations",
"write-heading-ids": "docusaurus write-heading-ids"
},
"dependencies": {
"@docusaurus/core": "3.1.1",
"@docusaurus/preset-classic": "3.1.1",
"@docusaurus/theme-mermaid": "^3.1.1",
"@easyops-cn/docusaurus-search-local": "^0.40.1",
"@mdx-js/react": "^3.0.0",
"clsx": "^2.0.0",
"prism-react-renderer": "^2.3.0",
"react": "^18.0.0",
"react-dom": "^18.0.0"
},
"devDependencies": {
"@docusaurus/module-type-aliases": "3.1.1",
"@docusaurus/types": "3.1.1"
},
"browserslist": {
"production": [
">0.5%",
"not dead",
"not op_mini all"
],
"development": [
"last 3 chrome version",
"last 3 firefox version",
"last 5 safari version"
]
},
"engines": {
"node": ">=18.0"
}
}
4 changes: 4 additions & 0 deletions docs/pages/advanced-topics/setting-up-a-testnet.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
title: Setting Up a Testnet
---

# Setting-Up a Testnet

To quickly test and run Lodestar we recommend starting a local testnet. We recommend a simple configuration of two beacon nodes with multiple validators
Expand Down
4 changes: 4 additions & 0 deletions docs/pages/beacon-management/mev-and-builder-integration.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
title: MEV and Builder Integration
---

# MEV & Merge

MEV is a term that refers to the bundling of transactions in one particular order to extract (mostly) arbitrage opportunities on the dApps and decentralized exchanges.
Expand Down
7 changes: 6 additions & 1 deletion docs/pages/contribution/depgraph.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,14 @@
---
title: Dependency Graph
---

## Lodestar monorepo dependency graph

This is a diagram of the various `lodestar-*` packages in the Lodestar monorepo and how they fit together:

!!! info
:::info
note: this dependency graph only applies to dependencies as they are used in the `src/` folders of each package, not in `test/`
:::

```mermaid
graph TD
Expand Down
27 changes: 13 additions & 14 deletions docs/pages/faqs.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,18 +6,17 @@ This section of the documentation will cover common questions and encounters oft

### Using Kubernetes

<!-- prettier-ignore-start -->
???+ note "Unknown arguments error"
Lodestar reads all environment variables prefixed with `LODESTAR` and will try to parse
them similar to command line arguments, meaning any unknown argument will cause an error.
```
✖ Unknown arguments: servicePort, servicePortEthConsensusP2p,
port9000Tcp, port9000TcpPort, port9000TcpProto, port9000TcpAddr, serviceHost
```
The extra arguments are present because Kubernetes automatically
[adds environment variables](https://kubernetes.io/docs/concepts/services-networking/service/#environment-variables)
to the Pod based on the name (`metadata.name`) defined in the associated `Service`.
To resolve the issue, this name has to be changed to something that does not start with `lodestar`.
:::note "Unknown arguments error"
Lodestar reads all environment variables prefixed with `LODESTAR` and will try to parse
them similar to command line arguments, meaning any unknown argument will cause an error.
```
✖ Unknown arguments: servicePort, servicePortEthConsensusP2p,
port9000Tcp, port9000TcpPort, port9000TcpProto, port9000TcpAddr, serviceHost
```
The extra arguments are present because Kubernetes automatically
[adds environment variables](https://kubernetes.io/docs/concepts/services-networking/service/#environment-variables)
to the Pod based on the name (`metadata.name`) defined in the associated `Service`.
To resolve the issue, this name has to be changed to something that does not start with `lodestar`.

Reference Issue: [#6045](https://github.com/ChainSafe/lodestar/issues/6045)
<!-- prettier-ignore-end -->
Reference Issue: [#6045](https://github.com/ChainSafe/lodestar/issues/6045)
:::
37 changes: 17 additions & 20 deletions docs/pages/getting-started/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,10 @@

The [`chainsafe/lodestar`](https://hub.docker.com/r/chainsafe/lodestar) Docker Hub repository is maintained actively. It contains the `lodestar` CLI preinstalled.

<!-- prettier-ignore-start -->
!!! info
The Docker Hub image tagged as `chainsafe/lodestar:next` is run on CI every commit on our `unstable` branch.
For `stable` releases, the image is tagged as `chainsafe/lodestar:latest`.
<!-- prettier-ignore-end -->
:::info
The Docker Hub image tagged as `chainsafe/lodestar:next` is run on CI every commit on our `unstable` branch.
For `stable` releases, the image is tagged as `chainsafe/lodestar:latest`.
:::

Ensure you have Docker installed by issuing the command:

Expand All @@ -25,25 +24,24 @@ docker pull chainsafe/lodestar
docker run chainsafe/lodestar --help
```

<!-- prettier-ignore-start -->
!!! info
Docker is the recommended setup for Lodestar. Use our [Lodestar Quickstart scripts](https://github.com/ChainSafe/lodestar-quickstart) with Docker for detailed instructions.
<!-- prettier-ignore-end -->
:::info
Docker is the recommended setup for Lodestar. Use our [Lodestar Quickstart scripts](https://github.com/ChainSafe/lodestar-quickstart) with Docker for detailed instructions.
:::

## Build from Source

### Prerequisites

Make sure to have [Yarn installed](https://classic.yarnpkg.com/en/docs/install). It is also recommended to [install NVM (Node Version Manager)](https://github.com/nvm-sh/nvm) and use the LTS version (currently v20) of [NodeJS](https://nodejs.org/en/).

<!-- prettier-ignore-start -->
!!! info
NodeJS versions older than the current LTS are not supported by Lodestar. We recommend running the latest Node LTS.
It is important to make sure the NodeJS version is not changed after reboot by setting a default `nvm alias default <version> && nvm use default`.
:::info
NodeJS versions older than the current LTS are not supported by Lodestar. We recommend running the latest Node LTS.
It is important to make sure the NodeJS version is not changed after reboot by setting a default `nvm alias default <version> && nvm use default`.
:::

!!! note
Node Version Manager (NVM) will only install NodeJS for use with the active user. If you intend on setting up Lodestar to run under another user, we recommend using [NodeSource's source for NodeJS](https://github.com/nodesource/distributions/blob/master/README.md#installation-instructions) so you can install NodeJS globally.
<!-- prettier-ignore-end -->
:::note
Node Version Manager (NVM) will only install NodeJS for use with the active user. If you intend on setting up Lodestar to run under another user, we recommend using [NodeSource's source for NodeJS](https://github.com/nodesource/distributions/blob/master/README.md#installation-instructions) so you can install NodeJS globally.
:::

### Clone repository

Expand Down Expand Up @@ -87,7 +85,6 @@ See [Command Line Reference](./../reference/cli.md) for further information.

## Install from NPM [not recommended]

<!-- prettier-ignore-start -->
!!! danger
For mainnet (production) usage, we only recommend installing with docker due to [NPM supply chain attacks](https://hackaday.com/2021/10/22/supply-chain-attack-npm-library-used-by-facebook-and-others-was-compromised/). Until a [safer installation method has been found](https://github.com/ChainSafe/lodestar/issues/3596), do not use this install method except for experimental purposes only.
<!-- prettier-ignore-end -->
:::danger
For mainnet (production) usage, we only recommend installing with docker due to [NPM supply chain attacks](https://hackaday.com/2021/10/22/supply-chain-attack-npm-library-used-by-facebook-and-others-was-compromised/). Until a [safer installation method has been found](https://github.com/ChainSafe/lodestar/issues/3596), do not use this install method except for experimental purposes only.
:::
4 changes: 4 additions & 0 deletions docs/pages/getting-started/quick-start.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
title: Quick Start
---

## Lodestar Quickstart

In order to make things easy for users to onboard and try the Ethereum **Proof of Stake** we have come up with [Lodestar quick start](https://github.com/ChainSafe/lodestar-quickstart) scripts!
Expand Down
Loading

0 comments on commit 41a8a35

Please sign in to comment.