Skip to content

Files

Latest commit

 

History

History
117 lines (80 loc) · 6.96 KB

site-intro.md

File metadata and controls

117 lines (80 loc) · 6.96 KB

Introduction

The Pulsar site is built with Docusaurus framework. You can find all the technical details on its docs.

Specifically, this chapter provides a writing syntax guide selecting knowledge for writing content of the site.

Source

Currently, the source of the site is located at the apache/pulsar-site repo.

Pages

Docusaurus provides three kinds of pages out-of-the-box: docs, blogs, and JSX pages.

The Pulsar site pages are of:

Page Type Source
User docs docs
  • docs/
  • versioned_docs/
  • versioned_sidebars/
  • sidebars.json
Contribution guides docs
  • contribute/
  • sidebarsDevelopment.js
Release notes docs
  • release-notes/
  • sidebarsReleaseNotes.js
Security docs
  • security/
Blogs blog
  • blog/
Client feature matrix docs
  • client-feature-matrix/
  • data/matrix.js
Other pages JSX pages
  • src/pages/

Besides, the site serves multiple static pages generated outside the framework, including API docs, reference docs, and swagger files. You can find them under the static folder.

Tools

preview.sh

The most commonly used tool is preview.sh. You can preview your local changes by:

./preview.sh

If you'd like to preview the site for a specific versions, you can pass the versions as an argument:

./preview.sh 4.0.x

See the previewing content guide for more details.

docker-compose.yaml

The preview.sh script uses the Docusaurus dev server for testing, which is different from the real Apache Web Server based env that serves the site online.

To emulate the server-side logics, like .htaccess rewrite rules, you can run:

yarn build
docker-compose up

Pytools

The site repo has a set of Python scripts for generating content and syncing/updating/publishing the site.

You can read the README file of pytools for details.

How-tos

This section holds common how-tos about website maintenance and troubleshooting.

How to fix search index mismatches?

First of all, you should get permission to access apache_pulsar crawler on Algolia Crawler console. You can email dev@pulsar.apache.org to ask for permission.

The most common fix for search index mismatches is to re-index the pages. You can do so by clicking "Restart crawling" button on the crawler page. Typically, it takes about 1 or 2 hours to complete.

How to preview changes locally?

If you make any changes to the site, before submitting a pull request, you're supposed to preview the changes locally. Read the previewing content guide about instructions.

How to update reference pages?

If you're gonna to update the content, read the update reference docs guide about the sources of reference pages.

If you're gonna to debug the reference generation process, read the reference-doc-generator usage section and its source code.

How to update data-driven pages?

You can update it by clicking on one of the ✍️ Edit <file_name> links below and submitting a Pull Request.