[v2] ☂️ Umbrella issue for v2 docs

wgao19 commented 5 years ago

Why contribute to Docusaurus v2 docs?

Docusaurus 2 is built with brilliance and so you may want to know how:
- your dev hot reload server builds and rebuilds in matters of seconds and milliseconds
- the client site will be an SPA, code-split by route, and pages are load lightning fast without even a spinner, how is that even possible 🌚
- site works even without javascript
Your very chance of experiencing docs composed from scratch, rephrase, from code, to human language on a popular OS project
Enjoy the pleasure of finding things out, teach and share it with others, practice writing skills
Slash her majesty will be your friend!

List of doc pieces up for grabbing

Docs

[x] Introduction / Contributing (#1700 @wgao19)
[x] Getting Started / Configurations → Themes, plugins, and presets configurations (#1929 thanks, @kadair!)
[ ] Getting Started / → themeConfig (relevant comment here)
[x] Getting Started / Initialization – #1655
[ ] Guides / Styling and Layouts → Styling components with CSS-in-JS frameworks
[x] Guides / Docs / Sidebar → Subcategories (#1670 @wgao19)
[x] Guides / Docs / Static Assets (@endiliey)
[x] Guides / Blogs (@dt97)
[x] Guides / Using Themes (#1645 @wgao19)
[x] Guides / Reaching Users → search (#1734 @endiliey)
[x] Guides / Reaching Users → analytics (#1678 @wgao19)
[x] Guides / Reaching Users → SEO (@wgao19)
[x] Guides / Deployment → Deployment with Netlify (#1719 @wgao19)
[x] Advanced Guides / Plugins → @docusaurus/plugin-google-gtag (@wgao19)
[x] Advanced Guides / Plugins → @docusaurus/plugin-ideal-image #1665 (@endiliey)
[x] Advanced Guides / Themes (#1645 @wgao19)
[x] Advanced Guides / Presets
[x] API Reference / Lifecycle API (WiP #1724 @wgao19) ~~API Reference / Themes API~~ ~~API Reference / Presets API~~
[x] docusaurus/link, useBaseUrl, head (wip @endiliey)

Miscellaneous

[x] Update all headings to sentence case (@yangshun)

Working on a doc piece

Within the markdown files for each of the doc pieces above, you may find in comment blocks some suggested outlines and reference materials:

Where to look in our code regarding the topic
Our v1 doc on the corresponding feature
Doc pieces from external projects on similar topics

As you work on the docs, use existing and external materials critically as examples or inspirations. You are more than welcome to explain things in your own style.

Also, feel free to ask us if you have any questions. You may tag us directly in your PR.

Adopting a doc piece

Create a PR and reference this issue
Within your PR, mark clearly which piece(s) you are working on
Once we see your PR, we'll mark in this issue that the corresponding piece is under work in progress by you
If you don't feel like continue working on the piece, close the PR so that other people can pick it up

Note that:

Your initial work does not have to include all the content for the piece, put WIP to indicate that you are working on it
You don't need to ask for permission or progression, etc. As long as there is no open PR (we will mark it beside the section), you can pull one up for the piece you are working on

Have you read the Contributing Guidelines on issues?

Yes

kushthedude commented 5 years ago

@wgao19 I would like to help with some of the parts

wgao19 commented 5 years ago

@kushthedude sounds great! You may PR directly for the piece you hope to work on. Thank you!

endiliey commented 5 years ago

assigning myself for docs on docusaurus/linj, withbaseurl, head, etc

dt97 commented 5 years ago

@wgao19 I would like to contribute to some of the docs namely Guides/Blogs for a start. I went through the documentation and the docs folder of the project and went through the guides-blog.md file. But am unable to understand what type of changes to be in that doc piece. I am a beginner by the way so any help on this would be really appreciated.

wgao19 commented 5 years ago

hey @dt97 thank you for offering to help! Based on the file names you mention, seems like you are looking at v1 docs. To clarify, this issue is for Docusaurus v2, which is a completely new static site generator with focus on doc sites.

If you are hoping to hop on to v2, the toc in this issue are referring to the docs in this directory. You should be able to match the files there. And within the actual files, there are "work in progress" status marks alongside some references.

Would you like to give them a try?

If you prefer to work on v1 docs as you may be using it, that is ok too. Please let me know which part you'd like to work on, and I'll see if I can provide any guidance on that.

dt97 commented 5 years ago

Thanks for the help. As suggested by you, I was looking out for the files in the wrong directory. I want to contribute to the docs namely Guides/Blogs for Docusaurus v2. I referred to the corresponding doc for Docusaurus v1 for getting some idea about it, but am unable to get a clear idea as to how to get Docusaurus v2 up and running on my macOS Mojave version 10.14.5 and access the Blogs section for creating Blogs.

Any guidance on getting started with Docusaurus v2 Blogs would be much appreciated. Meanwhile I am learning how to use Docusaurus and trying to understand its features by deploying a demo website going through Docusaurus Installation.

wgao19 commented 5 years ago

Hey @dt97, once again the Docusaurus Installation docs you are referring to is v1 docs. V2 docs are in this directory, and a website version is in Docusaurus v2 site.

dt97 commented 5 years ago

Thanks. Working on it!!!

dt97 commented 5 years ago

While going through the Docusaurus Contributing document found that the Discord Invite to join the docusaurus-2-dev channel seems to be invalid due to possible expiration of the invite. Not sure whether an issue needs to be created for this or not. Kindly look into it @wgao19 if possible, so that contributors can use the channel to their aid.

wgao19 commented 5 years ago

Hey @dt97 can try this link?

dt97 commented 5 years ago

Thanks @wgao19. The provided link works fine. Created a demo Blog markdown file in my system after looking at the sample Blogs present in the my-website folder of the Docusaurus v2 clone made following the Installation Guide. Exploring the various features involving creation of blogs in v2 release and planning the documentation content side by side. I hope it would be fine to take some inspiration from the v1 documentation for Creating Blogs for the format and content of the v2 documentation. Kindly correct me if I'm wrong. Planning to raise a PR soon if all goes well.

wgao19 commented 5 years ago

Hi @dt97 yes it is perfectly ok to use v1 as example. Looking forward to you PR :)

dt97 commented 5 years ago

@wgao19 have created a draft markdown file for blog.md for Docusaurus v2, am reviewing it and would raise a PR soon. I have shared the same with you on Discord. Your inputs on any modifications required are most welcome.

wgao19 commented 5 years ago

@dt97 sure, will do by this week

wgao19 commented 5 years ago

hey @dt97 i've read through the draft and it's looking great, plz go ahead and PR this in :]

dt97 commented 5 years ago

@wgao19 have raised a PR on this.

endiliey commented 5 years ago

Currently, it's not so obvious what are the available themeConfig option for @docusaurus/theme-classic. We should document it https://github.com/facebook/docusaurus/tree/master/packages/docusaurus-theme-classic

Example: https://github.com/facebook/docusaurus/pull/1909/files

dt97 commented 5 years ago

If I'm not wrong we need to augment the existing documentation for using-themes for v2 to add details about themeConfig option for @docusaurus/theme-classic right?

endiliey commented 5 years ago

You can start editing https://v2.docusaurus.io/docs/theme-classic for the theme config. I have provided an example

dt97 commented 5 years ago

Sure thing.

garretteklof commented 5 years ago

From what I'm reading it seems like the Infima framework powering v2 is not yet public? I'm trying to figure out the best way to override globals (fonts), and while I see how to override the coloring scheme, I am unable to find a full list of --ifm- variables. Is there anywhere I could find these? Also, how should I be directly accessing the document head to pull in customizations like Google Fonts? Do I setup my own theme to override the classic-theme? (edit: I see that I may just 'swizzle' the Layout component within the classic-theme) (Apologies if this is not where I'm supposed to be asking these questions)

endiliey commented 5 years ago

@garretteklof how about trying https://v2.docusaurus.io/docs/docusaurus.config.js#stylesheets

garretteklof commented 5 years ago

Yeah that would definitely allow me to import different styles, however that's not really my concern. I could probably hack in some !important statements inside the custom css stylesheet --- just trying to find the most elegant solution. Is there a full list of --ifm- variables anywhere? The Infima doesn't look to have the docs ready. Thanks for the help regardless. There is some pretty cool stuff being done within this project!

lzm0x219 commented 4 years ago

Is it possible to support @ material-ui / styles of material-ui？

yangshun commented 4 years ago

@vvni mind elaborating more?

lzm0x219 commented 4 years ago

@vvni mind elaborating more?

Using @ material-ui/styles on the server side requires additional processing, and the converted style needs to be entered into the html string.

lzm0x219 commented 4 years ago

@vvni mind elaborating more?

Thank you for your timely reply. Will you consider doing this support?

yangshun commented 4 years ago

Please file a separate issue, this issue is not the right place to discuss about it. We are shorthanded at the moment but maybe external contributors might help out.

lzm0x219 commented 4 years ago

Please file a separate issue, this issue is not the right place to discuss about it. We are shorthanded at the moment but maybe external contributors might help out.

Thank you for your reply.😬

yangshun commented 4 years ago

I was browsing the pages of https://v2.docusaurus.io and I felt that the docs were very complete and hence I came to look at this issue and just realized that this issue is already 95% done! Amazing work @wgao19 and the others!

yangshun commented 4 years ago

Our docs are in a much better place now compared to a year ago. There are some TODOs left in the code, but I'll clear them up. Closing this issue! Thanks again @wgao19! ❤️

restrictedCodex commented 3 years ago

Hey, I would like to help !! are there any tasks left I can work on? @wgao19

yangshun commented 3 years ago

@restrictedCodex this task is closed

facebook / docusaurus