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 2.11.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?​

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
  • Client feature matrix
    • data/matrix.js
    • client-feature-matrix/index.mdx

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

Was this helpful?