Errors in ReSpec Documentation

[Aman-Codes]

Important info

• URL to affected spec: Homepage
• I did a "hard refresh", but it's still busted.

Description of problem

What happened (e.g., it crashed)?:
I did a complete check of the ReSpec Documentation website and found the following errors

• This is a broken link present in homepage
• Element pre not allowed as child of element samp. According to HTML Standard samp should be a child of pre instead
• The align attribute on the th element is obsolete. Use CSS instead. (fix(docs): don't use obsolete align attribute in tables respec-web-services#129)
• Element blockquote not allowed as child of element samp
• Duplicate ID title. There are 2 instances of id="title" on same page. One for h1 id="title" class="title" and another one for section id="title" (fix(docs): fix duplicate id respec-web-services#126)

The complete report can be found here

Expected behavior (e.g., it shouldn't crash):
There should not be any errors

Optional, steps to reproduce:

1. Go to the ReSpec Documentation website.
2. View the page source code.

Also I am new to open source development and interested in contributing to this project. It would be great if you could guide me which files to modify to resolve this issue.

[sidvishnoi]

Hi @Aman-Codes,Thanks for reporting these issues!

As mentioned at https://respec.org/docs/#editing-this-document, the documentation text is maintained in the ReSpec Wiki as markdown files and the documentation website is generated from https://github.com/marcoscaceres/respec.org/blob/gh-pages/static/docs/src.html (a ReSpec document). To view changes to src.html locally, you need to clone the respec.org repo, run npx serve (assuming you've Node.js installed) in the static folder and visit http://localhost:5000/docs/src.html. Feel free to ask here if you face any difficulties.

This is a broken link present in homepage

Can you try if the workaround shared in markedjs/marked#1716 (comment) can work for us? You would need to edit the text in wiki, then wait a minute for those changes to get reflected in the docs website.

The align attribute on the th element is obsolete. Use CSS instead.

This one is pretty common with markdown processors. If we want to fix this, we can add a postProcess step at https://github.com/marcoscaceres/respec.org/blob/b89678f31934b917267baaa341f3c050743cb8ab/static/docs/src.html#L30 to convert align attributes to style or class attributes.

Element pre not allowed as child of element samp. According to HTML Standard samp should be a child of pre instead

Element blockquote not allowed as child of element samp

Good catch! This will require some investigation whether it's better to change the text in wiki, or we can do it as a postProcess step in the website.

Duplicate ID title. There are 2 instances of id="title" on same page. One for h1 id="title" class="title" and another one for section id="title"

I'll check what's causing this one 🙂

[Aman-Codes]

Thanks @sidvishnoi
I am facing some errors in running locally it locally can you please guide me

• I have forked marcoscaceres/respec.org and then cloned it in my local machine
• Run npm install
• Created a copy of .env.sample and saved it as .env
• Run npm start

Screnshot of error

Other information

• I also do not have the keys which needs to be added in .env file
• Node version v14.3.0
• Npm version v6.14.5

Can you tell me what I am missing. I think it is related to speced/respec-web-services#124 and speced/respec-web-services#123

[sidvishnoi]

I think it is related to speced/respec-web-services#124 and speced/respec-web-services#123

Correct. The workaround for editing docs would be:

1. Clone the repo.
2. Do not run npm install or npm start.
3. Switch to static directory (cd static)
4. npx serve and open the localhost URL in browser.
5. Navigate to /docs/src.html
6. Edit src.html in your editor, refresh in browser to see changes.

If you want to see the generated docs, install respec globally and run npx respec -s docs/src.html -o docs/index.html and visit /docs/ in browser.

[Aman-Codes]

Thanks finally got it correct now 😊

[sidvishnoi]

Also, you might not want to update the wiki directly during your experimentation (as it'll update https://respec.org/docs/). You can instead:

git clone https://github.com/w3c/respec.wiki.git
cd respec.wiki
npx serve -p 5001

and change https://github.com/marcoscaceres/respec.org/blob/b89678f31934b917267baaa341f3c050743cb8ab/static/docs/src.html#L85

-            include: `https://raw.githubusercontent.com/wiki/w3c/respec/${include}.md`,
+            include: `http://localhost:5001/${include}.md`,

(I know the getting started part is frustrating here. I'll see how we can improve this)

[Aman-Codes]

Also, you might not want to update the wiki directly during your experimentation (as it'll update https://respec.org/docs/). You can instead:

Yes will ensure that from next time onwards

[Aman-Codes]

Also, you might not want to update the wiki directly during your experimentation (as it'll update https://respec.org/docs/). You can instead:

git clone https://github.com/w3c/respec.wiki.git
cd respec.wiki
npx serve -p 5001

@sidvishnoi I am getting error in running these commands. It is making an empty folder in my local machine. I think it is due to invalid path of the file Google-Summer-of-Code-2018-:-Proposal.md.

Screenshot

[sidvishnoi]

TIL colons are not allowed in file names in Windows. Thanks!
Updated wiki. Please clone again.

[Aman-Codes]

@sidvishnoi Is there any way by which I can make a pull request to the wiki page instead of directly editing the hosted version so that project maintainers can review my work

[sidvishnoi]

Feel free to send the diff here 🙂

Or, you can push the wiki repo to your account:

# First, create a new repo from GitHub website, say, `aman-codes/respec-wiki`
git remote add aman https://github.com/aman-codes/respec-wiki.git
git push aman master

[Aman-Codes]

Thanks for your quick response 😁