webhintio / webhintio.github.io Goto Github PK

Might also make sense for it to be a link, but I’m not sure that’s required.

Pattern from https://ljwatson.github.io/design-patterns/aria-current/:

<nav aria-label="Breadcrumb">
    <ul>
        <li><a href="/">Home</a></li>
        <li><a href="/">Contact us</a></li>
        <li><a href="/" aria-current="location">Phone numbers</a></li>
    </ul>
</nav>

The current folder structure looks as follows:

It is not evident what does what and we will have to add more content once we start working on the scanner. Also the public folder is the only one that is being published into the website branch so we will need to change that.

Things that we need to do:

• Better separation between static site (hexo) and scanner (express) in the code. Probably have a src folder and then inside a couple other folders.
• Update scripts to generate the output under dist.
• Add a web.config file to the root of dist with rewrite rules for serving static assets or the scanner (related to #4).
• Update scripts to publish dist into the website branch with node_modules unless we found a way to run npm install in azure after deployment (not sure if it is done now automatically).
• Maybe move al the config files to its own folder and update all the tasks?

Need a Nellie in my phone homescreen!

Need to make some adjustments/add some CSS to the content in the documentation pages like https://sonarwhal.com/docs/developer-guide/events/list-of-events.html

All the bullets for list items make the page look cluttered. Also the subcontent of each 'event' could use some clearer hierarchy created through Typography and spacing.

• Style List items at top of the page

• Dev Guide: Style event content: the 'When?' and 'Remarks'

• Dev Guide: remove bullets from event content

• Add next/previous buttons as secondary navigation through documentation (see comps)

• Research UI patterns for Table of Contents

Will probably add more here as the pages are filled with content.

If we need it, let me know. I’ve been meaning to port https://github.com/aarongustafson/easy-validation.js to vanilla JS.

Need to have an option to search into the website, mainly across the documentation files.
Ideally similar to what ESLint does. We could:

• Use the same service (don't know if there is a free option).
• Use Azure Search

@sarvaje, @qzhou1607 I think you did a bit of research about this, right?

We need a 'sponsored by' section on the homepage right @molant?

Will also eventually need to add a 'companies using sonar' section too.

e.g: http://sonarwhal.com/docs/user-guide/rules/index.html

We need to update the documentation website when there are changes in Sonar.

Until we go public we can update/build the site each time there is a change in master, but we will have to look into a different strategy later (it could be as simple as having a development branch and we look only for changes in master).

In any case, we need to:

• Get notified of changes
• Download code
• Move things to the right place

Because repo is private for now, downloading the code might be a bit trickier right now :/

@alrra, ideas on how to do this? Guess that we can set up some SSH key in travis, get the latest version and go from there?

Right now we have all the user and dev guides in the master branch. I think we shouldn't have those (website branch is different).
Maybe we could have a script that pulls the latest version once the repo is OSS similar to what we are doing in travis?

@MicrosoftEdge/sonar-devs what do you think?

Missing the 'upload config file' and 'manual options' links under the search bar.

For multi-line items, at the first glance, I find it hard to distinguish where one item starts and the other begins.

Is there a sitewide footer forthcoming?

This will impact how we write sonar's documentation in the CLI project, but I think we should discuss it here because it is where it will be consumed.
Right now we user and developer guides with no main pages (#25). Inside each one, we have:

• separate .md files.
• sub folders with .md files.

What I'm thinking is the following:

• A file with the name readme.md will be the landing page for that section. E.g.:
  • /user-guide/readme.md will be the landing page for the user guide.
  • /user-guide/rules/readme.md will be the landing page for the rules. Right now the element in the ToC is not clickable, but it should.
• Any other items will be entries under that section in the ToC. E.g.:
  • /user-guide/rules/axe.md
• We can have files and folder at the same level in the ToC and the should look more or less the same (@ststimac looking at you for this). E.g.:
  • /user-guide/differences-among-collectors.md
  • /user-guide/rules/readme.md

@MicrosoftEdge/sonar-devs what do you think?

Ref: https://github.com/algolia/docsearch-scraper

I’m wondering: Does it make sense to use dl, dt, dd in lieu of div & p? The semantics might be better and it might provide opportunities to turn it all into a tree menu in the future.

Also recommend Title Case for the labels.

<dl class="module module--secondary table-of-contents" role="navigation">
    <dt class="toc-section-title--active">Collectors</dt>
    <dd>
        <ul class="toc-subsection-title">
            <li>
                <a href="/docs/developer-guide/collectors/how-to-develop-a-collector.html" class="toc-subsection-title--active">
                    How to develop a collector
                </a>
            </li>
        </ul>
    </dd>
    <dt class="toc-section-title--active">Rules</dt>
    <dd>
        <ul class="toc-subsection-title">
            <li>
                <a href="/docs/developer-guide/rules/how-to-test-rules.html" class="toc-subsection-title">
                    How to test rules
                </a>
            </li>
        </ul>
    </dd>
    <dt class="toc-section-title--active">Events</dt>
    <dd>
        <ul class="toc-subsection-title">
            <li>
                <a href="/docs/developer-guide/events/list-of-events.html" class="toc-subsection-title">
                    List of events emitted by a collector
                </a>
            </li>
        </ul>
    </dl>
</div>

Need GitHub SVG icon
Align icon to the right of the footer

• GitHub: #targetfetchstart
• Site: #targetfetch-start

Right now the website is only on an Azure Website. We need to have the right infrastructure in place to make it performant:

• Use a CDN for the assets (with right cache-control, etc.).
• Have a build process to minify, optimize, and update the assets/resources. We should also zopflify and brotlify the static files.
• Deploy to the right places the different assets.

Ideally we should be using webpack and @TheLarkInn helps with the webpack part.

RE the CDN not sure if using Azure ones or another one (that supports brotli) so there isn't that much dependency on Microsoft infrastructure.

It's a png and not svg.

e.g.: https://sonarwhal.com//docs/developer-guide/rules/how-to-create-a-rule.html

If I visit any other page, the footer is not there. E.g.:

• https://sonarwhal.com/about/faq/
• https://sonarwhal.com/docs/user-guide/rules/disallowed-headers.html

I'm seeing some discrepancies between machines when it comes to the way fonts are being rendered. Need to double check the correct weights are being applied.

Things to do:

• Create Azure website
• Update DNS domains
• Set up lets encrypt
• Enforce https via web.config
• Find a way to not need .html for the urls via web.config probably
• Configure brotli and zopfli in web.config until we have a CDN and can deploy to it
• Redirect www.sonarwhal.com to sonarwhal.com (DNS? web.config?)
• Make node listen to an specific path and update to the latest 7.x version
• Configure HTST and add domain to the HSTS Preload List

Seen throughout the site.

Recommendation (to not require CSS changes):

<a href="/" title="Return to the Sonar homepage" class="header__logo">
  <img src="/images/sonar-logo.svg" alt="Sonar">
</a>

Eating your own dog food.

Currently in subsections of user and developer guides.

Right now it looks like this:

Currently there’s no way to access it visually (though it is in the tab order).

The code block line numbers don't seem to me to be very useful. Also, for some cases, they just look weird:

@MicrosoftEdge/sonar-devs Thoughts?

Need to assess whether this will be easy to fix or if we'll hide search results on mobile.

@alrra I think this should come from sonar and should be calculated automatically between package version changes, tags, or any other way we seem appropriate. Thoughts?

@qzhou1607 your script should take it into account and put changelog.md in the right place.

Ref: #23 (comment)

This is from an iPhone 7+ using safari:

There is a vertical bar on the right.
Also when searching the page zooms which is a bit weird. Maybe we can remove the "sonar" text so it doesn't happen?

Media queries need to be adjusted to fix this issue in mobile Safari.

Currently aligned to the right but should line up on the left on smaller screens

Issue to track the work for the scanner part.
Depends on #4 to have something to render in the live site.

Various things regarding links:

• The "User Guide", "Rules" and "Developer Guide" in the middle are only clickable in the text. I think it should include the image as well
• Links in the homepage are not accurate. Here is the table:

• I don't think we need the changelog in the top finally
• About is missing Code of Conduct and Contributors
• Footer might not be in the bottom depending on the resolution showing a lighter blue below:
  

There is way to much css, we should clean up all the unneeded code.

Split lines from Markdown get split in HTML too:

This is not the case on GitHub:

We have a few code snippets in the website that are rendered as code but with no color at all:

We should have color syntax when possible. @qzhou1607, remarkable has syntax highlighting out of the box, but I don't know if the parser hexo uses has this option.

The code of conduct should be the same as the one in sonar and the website should use this file in the root to populate the section in the FAQ

It would be nice when hovering / tapping on a section title to show a # or an link icon , and by tapping / clicking on that, to link to that section.

E.g. from http://eslint.org/docs/rules/:

• eslint
• stylelint
• markdown
• editorconfig

They should be run on npm test (except editorconfig).

We need a search results page in case JS isn't enabled in the site.
@ststimac can you do the design, basic html and do a PR?
@qzhou1607 will do the backend part once I do #57 in that same branch before merging

This will have a few different iterations depending on what point in time we're at:

• MVP Scan results page, probably just the current state of the site that was scanned, no compare option, no charts

• Will need to slightly modify current design

• 2nd iteration, add compare to previous scan option

• Probably a 3rd iteration where we have enough data to start calculating average scores for the different rule categories like shown in the visual comps

This issue is present in the code from #7.

@ststimac I know I said this a couple of times, but the icebergs are great! 💜

We are going to use Hexo for the main site and express for the scan part.

We need to validate that we can integrate both nicely and that Hexo meets our needs. For the MVP we should have the following sections (plus a common header/footer accross all pages):

• Homepage with a form that takes you to /scan when user submits
  • /
• The scan page will be a small express server listening in /scan
  • It will have the same main layout as the other pages, shared somehow
  • In the main content it will say: “This is the scan coming from express”
• About section with some subsections (just a “you are in section XXXX” in markdown should be enough):
  • /about
  • /about/faq
  • /about/governance
• User guide and developer guide pulled from the /docs/ folder in sonar. We can do copy paste for now of those files:
  • /docs/user-guide and subfolders
  • /docs/developer-guide and subfolders
    In here we want to make something more complex than the other sections
  • There should be a ToC on each page based on the headings of the document
  • /docs/user-guide/rules/ should generate the list of rules automatically (and links to their documentation). Right now it is hardcoded in index.md but I think there should be some description in that page and then let the system populate the list automatically. This will be reused for other pages that have subpages.