You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@pulsar.apache.org by Sijie Guo <gu...@gmail.com> on 2018/07/27 21:18:23 UTC
[DISCUSS] New Pulsar Documentation Website
Hi all,
In the past few weeks, Chris Kellogg has been working on a new Pulsar
documentation website using Docusaurus <https://docusaurus.io/>. It is a
Facebook open source project, designed for easy to maintain open source
documentation websites.
It is a very popular and documentation-focused framework and used by a lot
of open source projects. It addressed a few problems that we had in current
documentation website.
- Sidebar: sidebar doesn't work well in current website. for example, it is
impossible to navigate to any documentation page on mobile phones; if you
have a smaller screen, you can not scroll down the sidebar to navigate to
the pages at the bottom.
- Hyperlinks on sections: there are some random characters generated in the
hyperlinks for markdown sections. It is non-deterministic and will cause
problems when linking documents.
Docusaurus gives us more benefits than current website.
- documentation focused: Docusaurus is designed for documentation websites.
so it brings the focus on writing documents in markdown. The framework
takes care of the rest of stuffs like versioning, sidebar and even
translations.
- much better sidebar: sidebar is working well across different browsers
and mobile phones.
- simpler hyperlinks: you can just link to other documents using document
filenames. it is working well for both website and navigating at github
directly. You don't have to compute any relative links.
- versioning: it manages all the versioning stuff.
- translations: it integrates Crowdin for translation contributions.
- search-box: a search-box integrated with Algolia.
- edit/translate button: for each document, it has edit button (for english
language) and translate button (for non-english language). so people can
quickly contribute documentation changes (such as fixing typos) by clicking
those buttons. It lowers
the contribution barrier.
Currently the new site is alive under
https://pulsar.incubator.apache.org/staging/. Please take a look at the new
website, try it out and give us feedbacks.
For contributors, I also wrote an instruction on how to contribute the
documentation. So you can get a sense on how to contribute documents in the
new site.
https://github.com/sijie/incubator-pulsar/blob/4a3a938d6ae1d9a5b1ae83d49293513c6e4f1711/site2/README.md
Last, big shout out to Chris for his great work on this!
- Sijie
Re: [DISCUSS] New Pulsar Documentation Website
Posted by Sijie Guo <gu...@gmail.com>.
Now the new website is live: https://pulsar.incubator.apache.org/
All documentations are versioned and localized. By default, it is pointing
to the latest released version. Documentation for different versions are
accessible from https://pulsar.incubator.apache.org/en/versions/
If you are updating documentation for latest development version, you
should modify the docs under
https://github.com/apache/incubator-pulsar/tree/master/site2/docs
If you want to fix documentation in a released version, you can modify the
docs under `versioned_docs`:
https://github.com/apache/incubator-pulsar/tree/master/site2/website/versioned_docs
I also put up a README for the instructions on how to contribute
documentation changes:
https://github.com/apache/incubator-pulsar/blob/master/site2/README.md
Let me know if you have any questions. More contributions are welcome!
- Sijie
On Thu, Aug 2, 2018 at 2:01 PM Sijie Guo <gu...@gmail.com> wrote:
> Hi all,
>
> Now the new website has all the content in-sync with existing website:
> https://pulsar.incubator.apache.org/staging/
>
> Since I am doing 2.1.0 release, I am planning to cut over the current
> website to new website at the last step of 2.1.0 release.
> All the documentation development will happen in the new website after
> that.
>
> Let me know if you have any questions or concerns. If I don't see any
> concerns in a few hours, I will move forward to cutover the new website.
>
> Thanks,
> Sijie
>
>
>
> On Fri, Jul 27, 2018 at 3:22 PM Jai Asher <ja...@gmail.com> wrote:
>
>> It looks really nice and has search functionality as well.
>>
>> Nice work @Chris.
>>
>> On Fri, Jul 27, 2018 at 2:18 PM, Sijie Guo <gu...@gmail.com> wrote:
>>
>> > Hi all,
>> >
>> > In the past few weeks, Chris Kellogg has been working on a new Pulsar
>> > documentation website using Docusaurus <https://docusaurus.io/>. It is
>> a
>> > Facebook open source project, designed for easy to maintain open source
>> > documentation websites.
>> >
>> > It is a very popular and documentation-focused framework and used by a
>> lot
>> > of open source projects. It addressed a few problems that we had in
>> current
>> > documentation website.
>> >
>> > - Sidebar: sidebar doesn't work well in current website. for example,
>> it is
>> > impossible to navigate to any documentation page on mobile phones; if
>> you
>> > have a smaller screen, you can not scroll down the sidebar to navigate
>> to
>> > the pages at the bottom.
>> > - Hyperlinks on sections: there are some random characters generated in
>> the
>> > hyperlinks for markdown sections. It is non-deterministic and will cause
>> > problems when linking documents.
>> >
>> > Docusaurus gives us more benefits than current website.
>> >
>> > - documentation focused: Docusaurus is designed for documentation
>> websites.
>> > so it brings the focus on writing documents in markdown. The framework
>> > takes care of the rest of stuffs like versioning, sidebar and even
>> > translations.
>> > - much better sidebar: sidebar is working well across different browsers
>> > and mobile phones.
>> > - simpler hyperlinks: you can just link to other documents using
>> document
>> > filenames. it is working well for both website and navigating at github
>> > directly. You don't have to compute any relative links.
>> > - versioning: it manages all the versioning stuff.
>> > - translations: it integrates Crowdin for translation contributions.
>> > - search-box: a search-box integrated with Algolia.
>> > - edit/translate button: for each document, it has edit button (for
>> english
>> > language) and translate button (for non-english language). so people can
>> > quickly contribute documentation changes (such as fixing typos) by
>> clicking
>> > those buttons. It lowers
>> > the contribution barrier.
>> >
>> >
>> > Currently the new site is alive under
>> > https://pulsar.incubator.apache.org/staging/. Please take a look at the
>> > new
>> > website, try it out and give us feedbacks.
>> >
>> > For contributors, I also wrote an instruction on how to contribute the
>> > documentation. So you can get a sense on how to contribute documents in
>> the
>> > new site.
>> >
>> > https://github.com/sijie/incubator-pulsar/blob/
>> > 4a3a938d6ae1d9a5b1ae83d49293513c6e4f1711/site2/README.md
>> >
>> > Last, big shout out to Chris for his great work on this!
>> >
>> > - Sijie
>> >
>>
>
Re: [DISCUSS] New Pulsar Documentation Website
Posted by Sijie Guo <gu...@gmail.com>.
Now the new website is live: https://pulsar.incubator.apache.org/
All documentations are versioned and localized. By default, it is pointing
to the latest released version. Documentation for different versions are
accessible from https://pulsar.incubator.apache.org/en/versions/
If you are updating documentation for latest development version, you
should modify the docs under
https://github.com/apache/incubator-pulsar/tree/master/site2/docs
If you want to fix documentation in a released version, you can modify the
docs under `versioned_docs`:
https://github.com/apache/incubator-pulsar/tree/master/site2/website/versioned_docs
I also put up a README for the instructions on how to contribute
documentation changes:
https://github.com/apache/incubator-pulsar/blob/master/site2/README.md
Let me know if you have any questions. More contributions are welcome!
- Sijie
On Thu, Aug 2, 2018 at 2:01 PM Sijie Guo <gu...@gmail.com> wrote:
> Hi all,
>
> Now the new website has all the content in-sync with existing website:
> https://pulsar.incubator.apache.org/staging/
>
> Since I am doing 2.1.0 release, I am planning to cut over the current
> website to new website at the last step of 2.1.0 release.
> All the documentation development will happen in the new website after
> that.
>
> Let me know if you have any questions or concerns. If I don't see any
> concerns in a few hours, I will move forward to cutover the new website.
>
> Thanks,
> Sijie
>
>
>
> On Fri, Jul 27, 2018 at 3:22 PM Jai Asher <ja...@gmail.com> wrote:
>
>> It looks really nice and has search functionality as well.
>>
>> Nice work @Chris.
>>
>> On Fri, Jul 27, 2018 at 2:18 PM, Sijie Guo <gu...@gmail.com> wrote:
>>
>> > Hi all,
>> >
>> > In the past few weeks, Chris Kellogg has been working on a new Pulsar
>> > documentation website using Docusaurus <https://docusaurus.io/>. It is
>> a
>> > Facebook open source project, designed for easy to maintain open source
>> > documentation websites.
>> >
>> > It is a very popular and documentation-focused framework and used by a
>> lot
>> > of open source projects. It addressed a few problems that we had in
>> current
>> > documentation website.
>> >
>> > - Sidebar: sidebar doesn't work well in current website. for example,
>> it is
>> > impossible to navigate to any documentation page on mobile phones; if
>> you
>> > have a smaller screen, you can not scroll down the sidebar to navigate
>> to
>> > the pages at the bottom.
>> > - Hyperlinks on sections: there are some random characters generated in
>> the
>> > hyperlinks for markdown sections. It is non-deterministic and will cause
>> > problems when linking documents.
>> >
>> > Docusaurus gives us more benefits than current website.
>> >
>> > - documentation focused: Docusaurus is designed for documentation
>> websites.
>> > so it brings the focus on writing documents in markdown. The framework
>> > takes care of the rest of stuffs like versioning, sidebar and even
>> > translations.
>> > - much better sidebar: sidebar is working well across different browsers
>> > and mobile phones.
>> > - simpler hyperlinks: you can just link to other documents using
>> document
>> > filenames. it is working well for both website and navigating at github
>> > directly. You don't have to compute any relative links.
>> > - versioning: it manages all the versioning stuff.
>> > - translations: it integrates Crowdin for translation contributions.
>> > - search-box: a search-box integrated with Algolia.
>> > - edit/translate button: for each document, it has edit button (for
>> english
>> > language) and translate button (for non-english language). so people can
>> > quickly contribute documentation changes (such as fixing typos) by
>> clicking
>> > those buttons. It lowers
>> > the contribution barrier.
>> >
>> >
>> > Currently the new site is alive under
>> > https://pulsar.incubator.apache.org/staging/. Please take a look at the
>> > new
>> > website, try it out and give us feedbacks.
>> >
>> > For contributors, I also wrote an instruction on how to contribute the
>> > documentation. So you can get a sense on how to contribute documents in
>> the
>> > new site.
>> >
>> > https://github.com/sijie/incubator-pulsar/blob/
>> > 4a3a938d6ae1d9a5b1ae83d49293513c6e4f1711/site2/README.md
>> >
>> > Last, big shout out to Chris for his great work on this!
>> >
>> > - Sijie
>> >
>>
>
Re: [DISCUSS] New Pulsar Documentation Website
Posted by Sijie Guo <gu...@gmail.com>.
Hi all,
Now the new website has all the content in-sync with existing website:
https://pulsar.incubator.apache.org/staging/
Since I am doing 2.1.0 release, I am planning to cut over the current
website to new website at the last step of 2.1.0 release.
All the documentation development will happen in the new website after
that.
Let me know if you have any questions or concerns. If I don't see any
concerns in a few hours, I will move forward to cutover the new website.
Thanks,
Sijie
On Fri, Jul 27, 2018 at 3:22 PM Jai Asher <ja...@gmail.com> wrote:
> It looks really nice and has search functionality as well.
>
> Nice work @Chris.
>
> On Fri, Jul 27, 2018 at 2:18 PM, Sijie Guo <gu...@gmail.com> wrote:
>
> > Hi all,
> >
> > In the past few weeks, Chris Kellogg has been working on a new Pulsar
> > documentation website using Docusaurus <https://docusaurus.io/>. It is a
> > Facebook open source project, designed for easy to maintain open source
> > documentation websites.
> >
> > It is a very popular and documentation-focused framework and used by a
> lot
> > of open source projects. It addressed a few problems that we had in
> current
> > documentation website.
> >
> > - Sidebar: sidebar doesn't work well in current website. for example, it
> is
> > impossible to navigate to any documentation page on mobile phones; if you
> > have a smaller screen, you can not scroll down the sidebar to navigate to
> > the pages at the bottom.
> > - Hyperlinks on sections: there are some random characters generated in
> the
> > hyperlinks for markdown sections. It is non-deterministic and will cause
> > problems when linking documents.
> >
> > Docusaurus gives us more benefits than current website.
> >
> > - documentation focused: Docusaurus is designed for documentation
> websites.
> > so it brings the focus on writing documents in markdown. The framework
> > takes care of the rest of stuffs like versioning, sidebar and even
> > translations.
> > - much better sidebar: sidebar is working well across different browsers
> > and mobile phones.
> > - simpler hyperlinks: you can just link to other documents using document
> > filenames. it is working well for both website and navigating at github
> > directly. You don't have to compute any relative links.
> > - versioning: it manages all the versioning stuff.
> > - translations: it integrates Crowdin for translation contributions.
> > - search-box: a search-box integrated with Algolia.
> > - edit/translate button: for each document, it has edit button (for
> english
> > language) and translate button (for non-english language). so people can
> > quickly contribute documentation changes (such as fixing typos) by
> clicking
> > those buttons. It lowers
> > the contribution barrier.
> >
> >
> > Currently the new site is alive under
> > https://pulsar.incubator.apache.org/staging/. Please take a look at the
> > new
> > website, try it out and give us feedbacks.
> >
> > For contributors, I also wrote an instruction on how to contribute the
> > documentation. So you can get a sense on how to contribute documents in
> the
> > new site.
> >
> > https://github.com/sijie/incubator-pulsar/blob/
> > 4a3a938d6ae1d9a5b1ae83d49293513c6e4f1711/site2/README.md
> >
> > Last, big shout out to Chris for his great work on this!
> >
> > - Sijie
> >
>
Re: [DISCUSS] New Pulsar Documentation Website
Posted by Sijie Guo <gu...@gmail.com>.
Hi all,
Now the new website has all the content in-sync with existing website:
https://pulsar.incubator.apache.org/staging/
Since I am doing 2.1.0 release, I am planning to cut over the current
website to new website at the last step of 2.1.0 release.
All the documentation development will happen in the new website after
that.
Let me know if you have any questions or concerns. If I don't see any
concerns in a few hours, I will move forward to cutover the new website.
Thanks,
Sijie
On Fri, Jul 27, 2018 at 3:22 PM Jai Asher <ja...@gmail.com> wrote:
> It looks really nice and has search functionality as well.
>
> Nice work @Chris.
>
> On Fri, Jul 27, 2018 at 2:18 PM, Sijie Guo <gu...@gmail.com> wrote:
>
> > Hi all,
> >
> > In the past few weeks, Chris Kellogg has been working on a new Pulsar
> > documentation website using Docusaurus <https://docusaurus.io/>. It is a
> > Facebook open source project, designed for easy to maintain open source
> > documentation websites.
> >
> > It is a very popular and documentation-focused framework and used by a
> lot
> > of open source projects. It addressed a few problems that we had in
> current
> > documentation website.
> >
> > - Sidebar: sidebar doesn't work well in current website. for example, it
> is
> > impossible to navigate to any documentation page on mobile phones; if you
> > have a smaller screen, you can not scroll down the sidebar to navigate to
> > the pages at the bottom.
> > - Hyperlinks on sections: there are some random characters generated in
> the
> > hyperlinks for markdown sections. It is non-deterministic and will cause
> > problems when linking documents.
> >
> > Docusaurus gives us more benefits than current website.
> >
> > - documentation focused: Docusaurus is designed for documentation
> websites.
> > so it brings the focus on writing documents in markdown. The framework
> > takes care of the rest of stuffs like versioning, sidebar and even
> > translations.
> > - much better sidebar: sidebar is working well across different browsers
> > and mobile phones.
> > - simpler hyperlinks: you can just link to other documents using document
> > filenames. it is working well for both website and navigating at github
> > directly. You don't have to compute any relative links.
> > - versioning: it manages all the versioning stuff.
> > - translations: it integrates Crowdin for translation contributions.
> > - search-box: a search-box integrated with Algolia.
> > - edit/translate button: for each document, it has edit button (for
> english
> > language) and translate button (for non-english language). so people can
> > quickly contribute documentation changes (such as fixing typos) by
> clicking
> > those buttons. It lowers
> > the contribution barrier.
> >
> >
> > Currently the new site is alive under
> > https://pulsar.incubator.apache.org/staging/. Please take a look at the
> > new
> > website, try it out and give us feedbacks.
> >
> > For contributors, I also wrote an instruction on how to contribute the
> > documentation. So you can get a sense on how to contribute documents in
> the
> > new site.
> >
> > https://github.com/sijie/incubator-pulsar/blob/
> > 4a3a938d6ae1d9a5b1ae83d49293513c6e4f1711/site2/README.md
> >
> > Last, big shout out to Chris for his great work on this!
> >
> > - Sijie
> >
>
Re: [DISCUSS] New Pulsar Documentation Website
Posted by Jai Asher <ja...@gmail.com>.
It looks really nice and has search functionality as well.
Nice work @Chris.
On Fri, Jul 27, 2018 at 2:18 PM, Sijie Guo <gu...@gmail.com> wrote:
> Hi all,
>
> In the past few weeks, Chris Kellogg has been working on a new Pulsar
> documentation website using Docusaurus <https://docusaurus.io/>. It is a
> Facebook open source project, designed for easy to maintain open source
> documentation websites.
>
> It is a very popular and documentation-focused framework and used by a lot
> of open source projects. It addressed a few problems that we had in current
> documentation website.
>
> - Sidebar: sidebar doesn't work well in current website. for example, it is
> impossible to navigate to any documentation page on mobile phones; if you
> have a smaller screen, you can not scroll down the sidebar to navigate to
> the pages at the bottom.
> - Hyperlinks on sections: there are some random characters generated in the
> hyperlinks for markdown sections. It is non-deterministic and will cause
> problems when linking documents.
>
> Docusaurus gives us more benefits than current website.
>
> - documentation focused: Docusaurus is designed for documentation websites.
> so it brings the focus on writing documents in markdown. The framework
> takes care of the rest of stuffs like versioning, sidebar and even
> translations.
> - much better sidebar: sidebar is working well across different browsers
> and mobile phones.
> - simpler hyperlinks: you can just link to other documents using document
> filenames. it is working well for both website and navigating at github
> directly. You don't have to compute any relative links.
> - versioning: it manages all the versioning stuff.
> - translations: it integrates Crowdin for translation contributions.
> - search-box: a search-box integrated with Algolia.
> - edit/translate button: for each document, it has edit button (for english
> language) and translate button (for non-english language). so people can
> quickly contribute documentation changes (such as fixing typos) by clicking
> those buttons. It lowers
> the contribution barrier.
>
>
> Currently the new site is alive under
> https://pulsar.incubator.apache.org/staging/. Please take a look at the
> new
> website, try it out and give us feedbacks.
>
> For contributors, I also wrote an instruction on how to contribute the
> documentation. So you can get a sense on how to contribute documents in the
> new site.
>
> https://github.com/sijie/incubator-pulsar/blob/
> 4a3a938d6ae1d9a5b1ae83d49293513c6e4f1711/site2/README.md
>
> Last, big shout out to Chris for his great work on this!
>
> - Sijie
>