momo-jun commented on code in PR #18071: URL: https://github.com/apache/pulsar/pull/18071#discussion_r997641699
########## site2/doc-guides/preview.md: ########## @@ -0,0 +1,164 @@ +# Pulsar Content Preview Guide + +> π©π»βπ« **Summary** +> +> This guide explains why and how to preview Pulsar content locally with detailed steps and various examples. + +**TOC** + +<!-- TOC --> + +- [Pulsar Content Preview Guide](#pulsar-content-preview-guide) + - [Why preview changes locally?](#why-preview-changes-locally) + - [How to preview changes locally?](#how-to-preview-changes-locally) + - [Prerequisites](#prerequisites) + - [Preview doc (markdown) changes](#preview-doc-markdown-changes) + - [Preview doc (Java API) changes](#preview-doc-java-api-changes) + - [Preview website changes](#preview-website-changes) + - [Stop preview](#stop-preview) + - [Maintenance info](#maintenance-info) + - [References](#references) + +<!-- /TOC --> + +## Why preview changes locally? + +It is **required** to preview your changes locally and attach the preview screenshots in your PR description. It brings many benefits, including but not limited to: + +* You can test your writings + + Itβs a way to check whether you use the correct [Pulsar Documentation Writing Syntax](https://docs.google.com/document/d/12De2btkDHQVaqUlHjTqERmroMLKGhHdiC7rEttFTyqc/edit#heading=h.y4c4051ki429) and debug issues. You **must ensure** docs can be compiled and published correctly. + +* You can get your PR merged more quickly. + + Reviewers know your changes clearly and can speed up the review process. + +## How to preview changes locally? + +Pulsar documentation is built using Docusaurus. To preview your changes as you edit the files, you can run a local development server that serves your website and reflect the latest changes. + +### Prerequisites + +To verify docs are built correctly before submitting a contribution, you should set up your local environment to build and display the docs locally. + +* Node >= 16.14 + +* Yarn >= 1.5 + +* Although you can use Linux, macOS, or Windows to build locally the Pulsar documentation, macOS is the preferred build environment as it offers the most complete support for documentation building. + +### Preview doc (markdown) changes + +Follow these steps to build the doc (markdown) preview on your local machine. + +1. Go to the correct repo. + + + ``` + cd pulsar/site2/website + ``` + +2. Run the following command to preview changes. + +* Preview **master** changes + + If you update master docs, use the following command. + + ``` + sh start.sh + ``` + +* Preview **historical** changes + + If you update versioned docs, use the following command. + + It may take a few more minutes to complete the process. + + ``` + sh start.sh <version-number> <version-number> + ``` + +  + +3. By default, a browser window will open at [http://localhost:3000](http://localhost:3000) to show the changes. + +  + +### Preview doc (Java API) changes + +Follow these steps to build the doc (Java API) preview on your local machine on the **master** branch. + +1. Go to the correct repo. + + ``` + cd pulsar/site2/tools + ``` + +2. Run the following command to generate the `.html` files. + + ``` + sh javadoc-gen.sh + ``` + +3. Open the target `.html` file to preview the updates. + + For example, if you change the [ConsumerBuilder.java](http://pulsar-client-api/src/main/java/org/apache/pulsar/client/api/ConsumerBuilder.java) for [Pulsar Java docs](https://pulsar.apache.org/api/client/2.11.0/org/apache/pulsar/client/api/ConsumerBuilder.html), you can navigate to the `generated-site/api/client/{version}/org/apache/pulsar/client/api/` directory and open the `ConsumerBuilder.html` file to preview the updates. + +### Preview website changes + +Pulsar website changes refer to all the changes made to the Pulsar website, including but not limited to the following pages: + +* [Release Notes page](https://pulsar.apache.org/release-notes/) β +* [Ecosystem page](https://pulsar.apache.org/ecosystem) β +* [Case studies page](https://pulsar.apache.org/case-studies) β +* β¦ +* (except docs β) + +Follow these steps to build the website preview on your local machine. + +1. Go to the correct repo. + + ``` + cd pulsar-site/site2/website-next + ``` + +2οΈ. Run the following command to preview changes. + + * Preview **master** changes + + If you submit changes to master, use the following command. + + + ``` + ./preview.sh + ``` + + * Preview **historical** changes + + ``` + ./preview.sh <version-number> <version-number> β¦ + ``` + + > βοΈ **Note** + > + > * Use a space between `<version-number> <version-number>`. + > + > * If you want to preview multiple version changes, append `<version-number>` with blanks. + > + > For example, `./preview.sh 2.9.1 2.9.2 2.9.3`. + +### Stop preview + +If you want to stop the preview, use one of the following methods. + +* Method 1: Switch to your command-line interface and press **Control+C**. + +* Method 2: Switch to your browser and close the preview page. + +### Maintenance info + +* For the old Pulsar website, using` yarn start` can preview all (master + historical) changes. However, to speed up the build process, for the new Pulsar website, using `./preview.sh `only preview master changes. Review Comment: ```suggestion * For the old Pulsar website, using ` yarn start` can preview all (master + historical) changes. However, to speed up the build process, for the new Pulsar website, using `./preview.sh `only preview master changes. ``` ########## site2/doc-guides/syntax.md: ########## @@ -0,0 +1,295 @@ +# Pulsar Documentation Writing Syntax Guide + +> π©π»βπ« **Summary** +> +> This guide explains how to write Pulsar documentation using the MDX-compatible markdown syntax. + +**TOC** + +<!-- TOC --> + +- [Pulsar Documentation Writing Syntax Guide](#pulsar-documentation-writing-syntax-guide) + - [Background](#background) + - [Why use new markdown syntax?](#why-use-new-markdown-syntax) + - [How to test doc changes?](#how-to-test-doc-changes) + - [Syntax](#syntax) + - [Markdown](#markdown) + - [Tab](#tab) + - [Code blocks](#code-blocks) + - [Admonitions](#admonitions) + - [Assets](#assets) + - [Indentation & space](#indentation--space) + - [Metadata](#metadata) + - [Tables](#tables) + - [Links](#links) + - [Anchor links](#anchor-links) + - [Links to internal documentation](#links-to-internal-documentation) + - [Links to external documentation](#links-to-external-documentation) + - [Link to a specific line of code](#link-to-a-specific-line-of-code) + - [Authoritative sources](#authoritative-sources) + - [Escape](#escape) + - [Headings](#headings) + - [References](#references) + +<!-- /TOC --> + +## Background + +The Pulsar documentation uses [Markdown](https://www.markdownguide.org/basic-syntax/) as its markup language and [Docusaurus](https://docusaurus.io/) for generating the documentation and website. + +> π΄ **BREAKING CHANGE** +> +> From 2022/5/18, you need to use **Markdown syntax that is compatible with MDX**. Otherwise, your changes can not be recognized by MDX and rendered properly. In this case, your PR can not be merged. + +### Why use new markdown syntax? + +The new Pulsar website is launched on 2022/5/11. It is upgraded to Docusaurus V2, which uses MDX as the parsing engine. MDX can do much more than just parsing standard Markdown syntax, like rendering React components inside your documents as well. However, **some previous documentation using Markdown syntax is incompatible with MDX**γ Consequently, you need to change the way you write. + +### How to test doc changes? + +- You can play with the MDX format in **[MDX Playground](https://mdxjs.com/playground/)** . Write some MDX to find out what it turns into. You can see the rendered result, the generated code, and the intermediary ASTs. This can be helpful for debugging or exploring. + +- For how to test doc changes locally, see [Pulsar Content Preview Guide](./preview.md). + +## Syntax + +> βοΈ**Note** +> +> This guide just highlights **some** important rules and frequently used syntax that is **different from the Markdown syntax used in the previous docs**. For the complete syntax guide, see [Docusaurus - Markdown Features](https://docusaurus.io/docs/next/markdown-features) and [MDX - Markdown](https://mdxjs.com/docs/what-is-mdx/#markdown). + +### Markdown + +* **Use Markdown rather than HTML** as much as possible, or else MDX may not recognize it. + + For example, when constructing complex tables, do not use HTML (`<table>`). + +* Use **closing** tags. + + <li></li> and <br></br> are especially useful for constructing complex tables, such as _creating a list_ and _adding a blank line_. + + π **Examples** + + ``` + <li>xxx β + <br>xxx β + <li>xxx</li> β + ``` + +  + + ``` + <br />xxx β wrap text in "next" line β + <br /><br />xxx β wrap text in "next next" line β + ``` + +  + +* If you need to use HTML, use **React** syntax for HTML tags. + + π **Examples** + + ``` + <span style="color: #bb3b3e;"></span> β + + <span style={{color: "#bb3b3e"}}>deleted</span> β + ``` + +### Tab + +The image below shows the differences for writing multiple tabs before and after. For how to write multiple tabs, see [Tabs](https://docusaurus.io/docs/next/markdown-features/tabs) Review Comment: ```suggestion The image below shows the differences in writing multiple tabs before and after. For how to write multiple tabs, see [Tabs](https://docusaurus.io/docs/next/markdown-features/tabs). ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
