chore(docs): add README to the docs

[BrunoQuaresma]

No description provided.

[codecov]

Codecov Report

Merging #3582 (4513d1e) into main (d8c3ba6) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##             main    #3582   +/-   ##
=======================================
  Coverage   59.21%   59.21%           
=======================================
  Files          35       35           
  Lines        1709     1709           
  Branches      379      379           
=======================================
  Hits         1012     1012           
  Misses        559      559           
  Partials      138      138           

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update d8c3ba6...4513d1e. Read the comment docs.

[jsjoeio]

We're working on the security fix so you can ignore the audit-ci failure.

For additional context, we're adding this because Bruno is working on deploying the code-server docs to a site and we need a Markdown file to render fo the home page. We'll most like change this later!

[jsjoeio]

I had an idea. @BrunoQuaresma instead of adding this file to /docs and duplicating README.md, could we add a script that just copies the README.md at the root to the /docs folder when we deploy the docs?

[JammSpread]

Does it have to be duplicated, couldn't the README just be moved to the 'docs/' folder since according to this:

If you put your README file in your repository's root, docs, or hidden .github directory, GitHub will recognize and automatically surface your README to repository visitors.

Although that may decrease the intuitiveness/simplicity of the repository and thus be a bad idea.

[BrunoQuaresma]

Thanks @JammSpread I didn't know about this one. I will try that.

[BrunoQuaresma]

The badge can be a problem for what we are trying to achieve with these changes - have a doc site for code-server docs. I'm wondering if makes sense we have something similar to what react-query does on their repo: https://github.com/tannerlinsley/react-query. @jsjoeio @JammSpread thoughts?

[jsjoeio]

I'm wondering if makes sense we have something similar to what react-query does on their repo:

Sorry @BrunoQuaresma - a bit dense this morning. What am I looking at in react-query's repo? I see their badges in the README. Or do you mean how the README is very short and then they have the /docs repo?

I do like what @JammSpread suggested. If GitHub surfaces the README.md that could be a solid approach.

[BrunoQuaresma]

Or do you mean how the README is very short and then they have the /docs repo?

Yes, I was talking about that.

I do like what @JammSpread suggested. If GitHub surfaces the README.md that could be a solid approach.

Me too, but I faced some issues trying to load the badge images with our current markdown parser and I was not able to solve 😞. Because of that, I think the first option can be a good approach for now.

We can have a README on root with the badges and a brief summary, and a docs/README.md with a more complete introduction. What do you think?

[jsjoeio]

We can have a README on root with the badges and a brief summary, and a docs/README.md with a more complete introduction. What do you think?

I think that could work. As long as we add a short blurb like "look in /docs for more documentation` or something, should be fine!

[jsjoeio]

I faced some issues trying to load the badge images with our current markdown parser

Would it be better if the badges were listed using HTML instead of markdown? We have options. See https://shields.io/

[bpmct]

I would be much more in favor of doing one of these options:

1. Use shields.io (like @jsjoeio suggested)
2. Update our hosted docs detect and to hide the shields from the root-level README
3. Change the codecov link (or whatever one is breaking outside of the repo) to show cdr/code-server stats, regardless where it is hosted.
4. Remove the culprit image

Reasoning being:

• We won't have to manually copy over ./README.md -> ./docs/README.md, or set a prescience for doing it (every release, every commit, etc?)
• docs/README.md can simply inform users of the hosted site

[bpmct]

I would also be in favor of a slimmed down ./README.md in favor of a larger one here. Not a fan of the duplication, but if necessary, we can go that route.

[jsjoeio]

@BrunoQuaresma anything you need from us to help you move this forward?

[BrunoQuaresma]

@jsjoeio I'm just aligning stuff with @bpmct before move forward, thanks for ask.

[bpmct]

We will likely be able to render the root-level README (with shields, if we want). So we will likely not need a second README in docs/. Still going over details :)

[bpmct]

Does it have to be duplicated, couldn't the README just be moved to the 'docs/' folder since according to this:

If you put your README file in your repository's root, docs, or hidden .github directory, GitHub will recognize and automatically surface your README to repository visitors.

Although that may decrease the intuitiveness/simplicity of the repository and thus be a bad idea.

@jsjoeio What are your thoughts on moving the readme as suggested above? This would reduce the complexity for the docs site

see https://github.com/bpmct/test-readme

[jsjoeio]

Thanks for the test repo. Seems fine to me too! I'll see if @code-asher or @oxy want to weigh in

[BrunoQuaresma]

I opened up a new PR to move the README. I will close this one, when we get that merged to no break the code-server docs build.

[jsjoeio]

I see #3663 has been merged. Does that mean we should close this @BrunoQuaresma?

[BrunoQuaresma]

@jsjoeio yes, doing it right now.