diff --git a/site2/README.md b/site2/README.md index 19bb4b94ec7a5..6783fcf1c6cc8 100644 --- a/site2/README.md +++ b/site2/README.md @@ -1,14 +1,12 @@ - - # The Pulsar website and documentation -This `README` is basically the meta-documentation for the Pulsar website and documentation. Here you'll find instructions on running the site locally +This `README` is basically the meta-documentation for the Pulsar website and documentation. You will find instructions on running the site locally. ## Tools Framework [Docusaurus](https://docusaurus.io/). -Ensure you have the latest version of [Node](https://nodejs.org/en/download/) installed. We also recommend you install [Yarn](https://yarnpkg.com/en/docs/install) as well. +Ensure you have installed the latest version of [Node](https://nodejs.org/en/download/). You can install [Yarn](https://yarnpkg.com/en/docs/install) as well. > You have to be on Node >= 8.x and Yarn >= 1.5. @@ -22,23 +20,26 @@ cd website yarn install yarn start ``` - -Note that the `/docs/en/` path shows the documentation for the latest stable release of Pulsar. Change it to `/docs/en/next/` to show your local changes, with live refresh. +> Notes +> +> 1. If you have installed `yarn`, you can skip the `yarn install` command. +> 2. After you enter the `yarn start` command, you will be navigated to a local address, for example, `http://localhost:3000`. Click `Docs` to see documentation for the latest release of Pulsar. +> 3. The `http://localhost:3000/en/versions` path shows the documentation for all versions. To view your local changes, click `Documentation` in **Latest Version**, or enter `http://localhost:3000/docs/en/next/standalone` in a browser. ## Contribute -The website is comprised of two parts, one is documentation, while the other is website pages (including blog posts). +The website is comprised of two parts: one is documentation, the other is website pages (including blog posts). -Documentation related pages are placed under `docs` directory. They are written in [Markdown](http://daringfireball.net/projects/markdown/syntax). -All documentation pages are versioned. See more details in [versioning](#versioning) section. +Documentation related pages are placed in the `docs` directory. They are written in [Markdown](http://daringfireball.net/projects/markdown/syntax). +All documentation pages are versioned. For more details, refer to [versioning](#versioning). -Website pages are non-versioned. They are placed under `website` directory. +Website pages are non-versioned. They are placed in the `website` directory. ### Documentation #### Layout -All the markdown files are placed under `docs` directory. It is a flat structure. +All the markdown files are placed in the `docs` directory. It is a flat structure. ``` ├── docs @@ -67,7 +68,7 @@ All the files are named in the following convention: -.md ``` -`` is the category within the sidebard that this file belongs to, while `` is the string to name the file within this category. +`` is the category within the sidebar that this file belongs to, while `` is the string to name the file within this category. There isn't any constraints on how files are named. It is just a naming convention for better maintenance. @@ -75,16 +76,16 @@ There isn't any constraints on how files are named. It is just a naming conventi ##### Markdown Headers -All the documents are the usual Markdown files. However you need to add some Docusaurus-specific fields in Markdown headers in order to link them +All the documents are usual Markdown files. However you need to add some Docusaurus-specific fields in Markdown headers in order to link them correctly to the [Sidebar](#sidebar) and [Navigation Bar](#navigation). -`id`: A unique document id. If this field is not present, the document's id will default to its file name (without the extension). +`id`: A unique document ID. If this field is not specified, the document ID defaults to its file name (without the extension). -`title`: The title of your document. If this field is not present, the document's title will default to its id. +`title`: The title of the document. If this field is not specified, the document title defaults to its id. `hide_title`: Whether to hide the title at the top of the doc. -`sidebar_label`: The text shown in the document sidebar for this document. If this field is not present, the document's `sidebar_label` will default to its title. +`sidebar_label`: The text shown in the document sidebar for this document. If this field is not specified, the document `sidebar_label` defaults to its title. For example: @@ -98,7 +99,7 @@ sidebar_label: Overview ##### Linking to another document -You can use relative URLs to other documentation files which will automatically get converted to the corresponding HTML links when they get rendered. +To link to other documentation files, you can use relative URLs, which will be automatically converted to the corresponding HTML links when they are rendered. Example: @@ -106,29 +107,29 @@ Example: [This links to another document](other-document.md) ``` -This markdown will automatically get converted into a link to /docs/other-document.html (or the appropriately translated/versioned link) once it gets rendered. +The markdown file will be automatically converted into a link to /docs/other-document.html (or the appropriately translated/versioned link) once it is rendered. -This can help when you want to navigate through docs on GitHub since the links there will be functional links to other documents (still on GitHub), -but the documents will have the correct HTML links when they get rendered. +This helps when you want to navigate through docs on GitHub since the links there are functional links to other documents (still on GitHub), +and the documents have the correct HTML links when they are rendered. #### Linking to javadoc of pulsar class -We have a [remarkable plugin](https://github.com/jonschlinkert/remarkable) for generating links to the javadoc for pulsar classes. -You can write them in following syntax: +We have a [remarkable plugin](https://github.com/jonschlinkert/remarkable) to generate links to the javadoc for Pulsar classes. +You can write them in the following syntax: ```shell {@inject: javadoc::} ``` -For example, following line generates a hyperlink to the javadoc of `PulsarAdmin` class. +For example, the following line generates a hyperlink to the javadoc of `PulsarAdmin` class. ```shell {@inject: javadoc:PulsarAdmin:/admin/org/apache/pulsar/client/admin/PulsarAdmin.html} ``` -#### Linking to files in Pulsar github repo +#### Linking to files in Pulsar GitHub repository -We are using same remarkable plugin to generate links to the files in Pulsar github repo. +We use the same [remarkable plugin](https://github.com/jonschlinkert/remarkable) to generate links to files in Pulsar GitHub repository. You can write it using similar syntax: @@ -136,20 +137,20 @@ You can write it using similar syntax: {@inject: github::} ``` -For example, following line generates a hyperlink to the dashboard Dockerfile. +For example, the following line generates a hyperlink to the dashboard Dockerfile. ``` {@inject: github:`Dockerfile`:/dashboard/Dockerfile} ``` -For more details about markdown features, you can read [here](https://docusaurus.io/docs/en/doc-markdown). +For more details about markdown features, read [here](https://docusaurus.io/docs/en/doc-markdown). #### Sidebar -All the sidebars are defined in a `sidebars.json` file under `website` directory. The documentation sidebar is named `docs` in that json structure. +All the sidebars are defined in a `sidebars.json` file in the `website` directory. The documentation sidebar is named `docs` in the JSON structure. -When you want to add a page to sidebar, you can add the document `id` you used in the document header to existing sidebar/category. In the blow example, -`docs` is the name of the sidebar, "Getting started" is a category within the sidebar and "pulsar-2.0" is the `id` of one of the documents. +When you want to add a page to sidebar, you can add the document `id` you used in the document header to the existing sidebar/category. In the example below, +`docs` is the name of the sidebar, "Getting started" is a category within the sidebar, and "pulsar-2.0" is the `id` of a document. ```bash { @@ -166,14 +167,11 @@ When you want to add a page to sidebar, you can add the document `id` you used i } ``` -For more details about versioning, you can read [here](https://docusaurus.io/docs/en/navigation). - #### Navigation To add links to the top navigation bar, you can add entries to the `headerLinks` of `siteConfig.js` under `website` directory. -See [Navigation and Sidebars](https://docusaurus.io/docs/en/navigation) in Docusaurus website to learn different types of links -you can add to the top navigation bar. +To learn different types of links you can add to the top navigation bar, refer to [Navigation and Sidebars](https://docusaurus.io/docs/en/navigation). ## Versioning @@ -183,34 +181,34 @@ Documentation versioning with Docusaurus becomes simpler. When done with a new r yarn run version ${version} ``` -This will preserve all markdown files currently in `docs` directory and make them available as documentation for version `${version}`. +This preserves all markdown files in the `docs` directory and make them available as documentation for version `${version}`. Versioned documents are placed into `website/versioned_docs/version-${version}`, where `${version}` is the version number you supplied in the command above. Versioned sidebars are also copied into `website/versioned_sidebars` and are named as `version-${version}-sidebars.json`. -If you wish to change the documentation for a past version, you can access the files for that respective version. +If you want to change the documentation for a previous version, you can access files for that respective version. -For more details about versioning, you can read [here](https://docusaurus.io/docs/en/versioning). +For more details about versioning, refer to [Versioning](https://docusaurus.io/docs/en/versioning). ## Translation and Localization -Docusaurus allows for easy translation functionality using [Crowdin](https://crowdin.com/). +Docusaurus makes it easy to use translation functionality using [Crowdin](https://crowdin.com/). All the markdown files are written in English. These markdown files are uploaded to Crowdin -for translation by the users within a community. Top-level pages are also written in English. +for translation by users within a community. Top-level pages are also written in English. The strings that are needed to be translated are wrapped in a `` tag. -[Pulsar Website Build](https://builds.apache.org/job/pulsar-website-build/) will automatically -pulling down and uploading translations for all the pulsar website documentation files. Once -it pulls down those translations from Crowdin, it will build those translations into the website. +[Pulsar Website Build](https://builds.apache.org/job/pulsar-website-build/) +pulls down and uploads translation for all the Pulsar website documentation files automatically. Once +it pulls down translation from Crowdin, it will build the translation into the website. -### Contribute Translations +### Contribute Translation -All the translations are stored and managed in this [Pulsar Crowdin project](https://crowdin.com/project/apache-pulsar). -If you would like to contribute translations, you can simply create a Crowdin account, join the project and make contributions. -Crowdin provides very good documentation for translators. You can read [those documentations](https://support.crowdin.com/crowdin-intro/) -to start contributing. +Translation is stored and managed in the [Pulsar Crowdin project](https://crowdin.com/project/apache-pulsar). +To contribute translation, you can simply create a Crowdin account, join the project and make contributions. +Crowdin provides very good documentation for translators. You can read [Crowdin Knowledge Base](https://support.crowdin.com/crowdin-intro/) +before contributing. -Your contributed translations will be licensed under [Apache License V2](https://www.apache.org/licenses/LICENSE-2.0). -Pulsar Committers will review those translations. If your translations are not reviewed or approved by any committers, -feel free to reach out to use via [slack channel](https://apache-pulsar.herokuapp.com/) or [mailing lists](https://pulsar.apache.org/contact/). +Translation you contribute is licensed under [Apache License V2](https://www.apache.org/licenses/LICENSE-2.0). +Pulsar Committers will review translation. If your translation is not reviewed or approved by any committer, +feel free to reach out via [slack channel](https://apache-pulsar.herokuapp.com/) or [mailing lists](https://pulsar.apache.org/contact/). \ No newline at end of file