Skip to main content

Introduction

The Pulsar site is built with Docusaurus framework. You can find all 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/
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 2.11.x

See the previewing content guide for more details.

docker-compose.yaml

The preview.sh script use 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?

The following pages contain data-driven tables:

  • Case studies
    • data/users.js
    • src/pages/case-studies.js
  • Downloads
    • releases.json
    • data/connectors.js
    • data/release-cpp.js
    • data/release-pulsar-manager.js
    • data/release-pulsar-adapters.js
    • src/components/download.tsx
    • src/pages/download.mdx
  • Ecosystem
    • data/ecosystem.js
    • src/pages/ecosystem.js
  • Events
    • data/events.js
    • src/pages/events.js
  • Release notes
    • data/release-*.js
    • release-notes/
    • src/components/ClientReleaseTable.js
    • src/components/PulsarReleaseTable.js
  • Resources
    • data/resources.js
    • src/pages/resources.js
  • Team
    • data/team.js
    • src/pages/team.js

Additionally, PMC members can generate the team.js file as @lhotari did in https://github.com/apache/pulsar-site/pull/387.