Skip to main content

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:

PageTypeSource
User docsdocs
  • docs/
  • versioned_docs/
  • versioned_sidebars/
  • sidebars.json
Contribution guidesdocs
  • contribute/
  • sidebarsDevelopment.js
Release notesdocs
  • release-notes/
  • sidebarsReleaseNotes.js
Securitydocs
  • security/
Blogsblog
  • blog/
Client feature matrixdocs
  • client-feature-matrix/
  • data/matrix.js
Other pagesJSX 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 [email protected] 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.

Was this helpful?
💡 Suggest changes🛟 Get support