Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[v2] ☂️ Umbrella issue for v2 docs #1640

Closed
18 of 20 tasks
wgao19 opened this issue Jul 6, 2019 · 33 comments
Closed
18 of 20 tasks

[v2] ☂️ Umbrella issue for v2 docs #1640

wgao19 opened this issue Jul 6, 2019 · 33 comments

Comments

@wgao19
Copy link
Contributor

@wgao19 wgao19 commented Jul 6, 2019

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

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

Miscellaneous

  • 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
Copy link

@kushthedude kushthedude commented Jul 15, 2019

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

Loading

@wgao19
Copy link
Contributor Author

@wgao19 wgao19 commented Jul 15, 2019

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

Loading

@endiliey endiliey added the 2.x label Jul 18, 2019
@wgao19 wgao19 mentioned this issue Jul 19, 2019
@endiliey endiliey changed the title ☂️ Umbrella issue for v2 docs [v2] ☂️ Umbrella issue for v2 docs Jul 24, 2019
@endiliey
Copy link
Contributor

@endiliey endiliey commented Aug 5, 2019

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

Loading

@dt97
Copy link
Contributor

@dt97 dt97 commented Aug 22, 2019

@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.

Loading

@wgao19
Copy link
Contributor Author

@wgao19 wgao19 commented Aug 25, 2019

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.

Loading

@dt97
Copy link
Contributor

@dt97 dt97 commented Aug 26, 2019

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.

Loading

@wgao19
Copy link
Contributor Author

@wgao19 wgao19 commented Aug 27, 2019

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.

Loading

@dt97
Copy link
Contributor

@dt97 dt97 commented Aug 29, 2019

Thanks. Working on it!!!

Loading

@dt97
Copy link
Contributor

@dt97 dt97 commented Sep 4, 2019

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.

Loading

@wgao19
Copy link
Contributor Author

@wgao19 wgao19 commented Sep 4, 2019

Hey @dt97 can try this link?

Loading

@dt97
Copy link
Contributor

@dt97 dt97 commented Sep 4, 2019

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.

Loading

@wgao19
Copy link
Contributor Author

@wgao19 wgao19 commented Sep 5, 2019

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

Loading

dt97 added a commit to dt97/docusaurus that referenced this issue Sep 15, 2019
@dt97
Copy link
Contributor

@dt97 dt97 commented Sep 15, 2019

@wgao19 have raised a PR on this.

Loading

dt97 added a commit to dt97/docusaurus that referenced this issue Sep 24, 2019
yangshun added a commit that referenced this issue Oct 5, 2019
* docs(v2): contributing for v2 #1640

* deleted blog.md

* docs(v2): contributing for v2 (#1640)

* docs(v2): blog (#1640)

* Update blog.md
@endiliey
Copy link
Contributor

@endiliey endiliey commented Oct 29, 2019

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

Loading

@dt97
Copy link
Contributor

@dt97 dt97 commented Oct 29, 2019

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?

Loading

@endiliey
Copy link
Contributor

@endiliey endiliey commented Oct 30, 2019

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

Loading

@dt97
Copy link
Contributor

@dt97 dt97 commented Oct 30, 2019

Sure thing.

Loading

@garretteklof
Copy link

@garretteklof garretteklof commented Nov 6, 2019

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)

Loading

@endiliey
Copy link
Contributor

@endiliey endiliey commented Nov 7, 2019

Loading

@garretteklof
Copy link

@garretteklof garretteklof commented Nov 8, 2019

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!

Loading

@0x219

This comment was marked as off-topic.

@yangshun

This comment was marked as off-topic.

@0x219

This comment was marked as off-topic.

@0x219

This comment was marked as off-topic.

@yangshun

This comment was marked as off-topic.

@0x219

This comment was marked as off-topic.

@yangshun
Copy link
Member

@yangshun yangshun commented Feb 24, 2020

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!

Loading

@yangshun yangshun unpinned this issue Feb 24, 2020
@yangshun
Copy link
Member

@yangshun yangshun commented Jun 5, 2020

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! ❤️

Loading

@restrictedCodex
Copy link

@restrictedCodex restrictedCodex commented Sep 26, 2021

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

Loading

@yangshun
Copy link
Member

@yangshun yangshun commented Sep 26, 2021

@restrictedCodex this task is closed

Loading

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
9 participants