Go to file
Jimmy Debe 278d706a47
Merge pull request #6 from vacp2p/develop
Support latex rendering
2024-09-24 09:02:44 -04:00
.husky Initial commit 2024-03-12 03:11:16 +09:00
docs feat: support latex rendering 2024-09-24 04:32:35 +09:00
docusaurus-utils chore: Build streamlined (#4) 2024-06-25 07:54:16 +02:00
src feat: support latex rendering 2024-09-24 04:32:35 +09:00
static chore: Routing Refactor (#3) 2024-04-25 09:29:22 +02:00
.env.example chore: Build streamlined (#4) 2024-06-25 07:54:16 +02:00
.gitignore chore: Build streamlined (#4) 2024-06-25 07:54:16 +02:00
.prettierignore Initial commit 2024-03-12 03:11:16 +09:00
.prettierrc Initial commit 2024-03-12 03:11:16 +09:00
Jenkinsfile chore: Build streamlined (#4) 2024-06-25 07:54:16 +02:00
README.md chore: Build streamlined (#4) 2024-06-25 07:54:16 +02:00
babel.config.js Initial commit 2024-03-12 03:11:16 +09:00
docusaurus.config.js feat: support latex rendering 2024-09-24 04:32:35 +09:00
package.json feat: support latex rendering 2024-09-24 04:32:35 +09:00
sidebars.js Initial commit 2024-03-12 03:11:16 +09:00
tsconfig.json Initial commit 2024-03-12 03:11:16 +09:00
yarn.lock feat: support latex rendering 2024-09-24 04:32:35 +09:00

README.md

Vac RFC Website

This repository contains documents that have been discussed and pushed from the rfc-index repository. Pull requests opened in this repository must relate to Vac RFC website updates, pull request related to RFC specifications must be open in the rfc-index repository.

How to Run Locally

  1. Clone this repository
$ git clone https://github.com/acid-info/logos-docs-template.git
  1. Install the dependencies:
$ yarn install
  1. Create .env and run the scraping script (make sure you're located in the root of the project when running this command)
$ yarn scrape
  1. Start the website:
$ yarn start
  1. Visit http://localhost:3000 in your browser

Configuration

The template repository for docs using logos-docusaurus-plugins. Edit the docusaurus.config.js file in the repository's root directory, and update the value of the businessUnit field in presets section; below is a list of valid values:

  • Logos
  • Codex
  • Waku
  • Nimbus
  • Nomos
  • VacResearch
  • Acid.info

Example:

presets: [
  [
    '@acid-info/logos-docusaurus-preset',
    {
      businessUnit: 'Codex',
    },
  ],
],

This is typically sufficient for most cases, as the Logos plugins will automatically populate other configurations related to the specified business unit. If you encounter any errors in the information provided by Logos Plugins, please visit the Logos Docusaurus Plugins repository and open an issue.

Docs Setup

This template does not include a landing page. Please review the routeBasePath: '/' setting in the docusaurus.config.js file.

presets: [
    [
      '@acid-info/logos-docusaurus-preset',
      /** @type {import('@acid-info/logos-docusaurus-preset').PluginOptions} */
      ({
        businessUnit: 'Codex',
        theme: {
          name: 'default',
          options: {
            customCss: [require.resolve('./src/css/custom.scss')],
            docs: {
              default: {
                sidebar: {
                  hide: false,
                },
              },
            },
          },
        },
        docs: {
          routeBasePath: '/', // the index.md becomes the index page
        },
        og: {},
      }),
    ]
]

The content in docs/index.md will serve as the root page for your documentation.

For additional customization options, please refer to the Docusaurus Configuration.

Adding docs

To add a document, create a .md or mdx file within the docs directory. You can use Frontmatter to add metadata to your markdown file.

Docusaurus Config

You can find instructions for adding additional documentation sections, implementing localization, and managing versioning on the Docusaurus website.

Please note that theme customization is somewhat restricted; for more detailed instructions on customizing your theme, visit the Logos Docusaurus Theme repository.

Custom CSS

By default, this template utilizes the CSS styles defined in the logos-docusaurus-plugins package. You have the option to define custom CSS in src/css/custom.scss.

How to Run a Static Build (Production Build)

  1. Generate static files for production:
  • If you have ran yarn scrape previously, you can just run
$ yarn build
  • If not, you can use the next command for complete scrape and build process
$ yarn build:full

The static files will be created in the build directory.

  1. Serve the static build:
$ yarn serve

CI/CD

The hosting is done using Caddy server with Git plugin for handling GitHub webhooks.

Information about deployed build can be also found in /build.json available on the website.

Change Process

  1. Create a new working branch from develop: git checkout develop; git checkout -b my-changes.
  2. Make your changes, push them to the origin, and open a Pull Request against the develop branch.
  3. After approval, merge the pull request, and verify the changes on the staging server (e.g., https://dev.vac.dev).
  4. When ready to promote changes to the live website, rebase the master branch on the staging changes: git checkout master; git pull origin master; git rebase origin/develop; git push.