WIP: New website

[EduardoLopes]

Current look

Still missing:

• Dark Mode
• Menu for others pages (I think it's good on the sidebar)
• Support for screen-readers

[sebmck]

Woah, I like it! Haven't reviewed anything yet but I really like the design screenshots.

[matvp91]

@sebmck imo the only thing left in order to replace the Docusaurus build is a proper footer. Could you double check if I'm missing something? If not, I should get this done during the weekend.

[bitpshr]

I think this looks great. Some general questions and comments:

• Should the Installation section be combined with Getting Started, especially if users will be directed to NPM? The installation instructions will be one line and it feels odd to have them as their own top-level heading.
• I think we should have a "detail" page for each stable command (like Linting currently has). If a command isn't stable enough, it feels odd to even list it in the Getting Started section at all.

[matvp91]

There's a separate section in #509 for "Linting", although it's not a seperate page.

I agree with your first comment, the shorter the docs, the easier it gets for people to read through them.

If agreed upon, we should merge that PR in here to avoid confusion.

[matvp91]

We're getting to a point where the new documentation is good enough to be released. Although, I'd like to raise several questions that are worth discussing:

• Will there ever be a need for a top navigation bar? If not, I'd like to figure out something different. The fact that we have a fixed navbar on top (that is especially visible on mobile), makes the titles show below the fixed header when we navigate to a different anchor. (1)
• Clicking nav items will only be in "active" state after the scroll animation, user actions should have immediate feedback. (1)
• There's a bunch of improvements that can be made on mobile:
  • When using the sidebar to navigate to a different anchor, we should close the sidebar.
  • The sidebar does not fully cover the width of the screen, clicking outside should close the sidebar (preferrably a semi transparant black background to keep focus on the menu).
• Support for screen-readers / wai-aria.
• Anchors do not update when scrolling through the page, this will cause confusion when people start sharing sections. (1)
• TOC is fully client-side at the moment, let's move TOC generation to a build step in Eleventy, or have a better client-side implementation that covers most of the issues mentioned above.

1. These should be fixed in our own TOC implementation, this requires us to write a bit of JavaScript, let's use Rome to transpile the JS written for the docs.

[Kelbie]

This is looking really good so far!

The "Testing" and "Type checking" sections are not highlighted on the nav unlike all the other elements:

[EduardoLopes]

If there will be others pages, i think we should use the top bar for that. And keep only table of contents in the sidebar. Or make a section in the side bar, for links that will lead to another page, so the user know what each type of link makes once you click! The top bar seems like a better solution.

Generate the TOC on a build step in Eleventy would be great.

[EduardoLopes]

@KevinKelbie it's because you can't go all the way down so the heading get close to the top and highlight

[EduardoLopes]

@matvp91

When using the sidebar to navigate to a different anchor, we should close the sidebar.

Didn't really got this line. Clicking a toc link should close the sidebar?

The content overlay when sidebar is open is done! Clicking outside the sidebar, closes!

[matvp91]

@EduardoLopes correct, I assume when someone clicks on a TOC item, they'll want to see the content afterwards.

Why exactly would we need an event listener on touchstart? The click event handler is called on mobile too.

Nice work!

[EduardoLopes]

Dark mode is basically finished. I just need to find a place for the toggle button. Right now, it's in the footer. I think i'll place it at the bottom of the side bar.

[kennetpostigo]

Should there be a dedicated section to testing? Documenting the built-in test framework api?

[sebmck]

Preferrably not. The only thing that should be documented is the linter which is the only part we will actively support and ensure compatibility across semver. Might be worth documenting the basics of the testing API for contributors though.

[EduardoLopes]

I did my best to support screen readers. Would be nice if anyone here, with more experience on making web pages accessibly, review the website and point out if i'm missing something.

The markdown compiler doesn't compile the content to semantic html. Each part with a heading should be separated by sections tags. But this is how github compiles markdown anyways, so i think there's no problems for screen readers?! i'm not sure

This is the document structure right now:

• 1 [document] Rome
  • 1 [nav] Site Navigation
  • 2 [nav] Page Navigation
• 2 [h1] Your next-gen JavaScript toolchain.
  • 1 [h2] Focus on code, let Rome take care of the rest!
• 3 [h1] Introduction
• 4 [h1] Installation
• 5 [h1] Getting started
• 6 [h1] Usage
  • 1 [h2] rome init
  • 2 [h2] rome run
  • 3 [h2] rome lint
  • 4 [h2] rome compile
  • 5 [h2] rome parse
• 7 [h1] Linting
  • 1 [h2] Interpreting the result
  • 2 [h2] Example
• 8 [h1] Contributing
  • 1 [h2] Testing
  • 2 [h2] Type checking
• 9 [h1] Footer
  • 1 [nav] Community
  • 2 [nav] Resources

[sebmck]

Thank you so much for the work @EduardoLopes and @matvp91! I'm going to merge this so we can be more incremental with documentation changes and review. I'm going to let the site build and deploy to https://romejs.dev/ then I'll change the site to just a white page with "Coming soon" since having the current website up is confusing. Later we can then switch it over.