search

arduino / reference-en

Editable source for the Arduino Reference
https://www.arduino.cc/reference/en/
Other
165 stars 734 forks source link

Unnecessary anchor tags in markup #545

Open per1234 opened 5 years ago

per1234 commented 5 years ago

The markdown for each reference page creates a few anchor tags:

[#overview]
[#howtouse]
[#see_also]

However, it's not clear to me that these are needed. The reason is that anchors are automatically generated for each heading in the page. This means that https://www.arduino.cc/reference/en/language/functions/digital-io/digitalread/#_example_code works just as well as https://www.arduino.cc/reference/en/language/functions/digital-io/digitalread/#howtouse. For this reason, it seems like the manually added anchors only clutter up the reference source, making the content less friendly to casual contributors. Perhaps there is some purpose to these I'm not aware of? If not, I propose that I remove them, and update any links in the reference content that use them.

SeppPenner commented 5 years ago

@per1234 I haven't seen the purpose of these either. I first thought that they are needed to fill e.g. the see also section with links from pages on the same folder level (But that's not true).

animeshsrivastava24 commented 5 years ago

Yes, I too have a similar doubt regarding them. In initial process of grammar check and typo correction I didn't found their use or visibility ( I thought I missed something). Also while few translations, I landed upon them again and checked whether they made an importance if left untreated (I didn't found a problem). [EDIT: The content below shows importance of the anchor tags] While searching for their importance, I landed on this website

https://daveabrock.com/2018/03/03/using-anchor-links-in-markdown/

The information mentioned on the website is as follows:

I wasn't sure how to use anchor links in Markdown. These come in handy when you have a long post and want to link to different sections of a document for easy navigation.

The nice thing about Markdown is that it plays so well with straight HTML - so I was pleased to get it working on the first try.

First, add an anchor as regular HTML in your Markdown element. Here, it is right at a heading.

### <a id="MyHeading"></a>My Heading ###

Now, I can link it using a standard Markdown link.

Where is my [heading](#MyHeading)?

Another webpages which tell some importance about them: https://github.com/markedjs/marked/issues/92 https://guides.codechewing.com/add-custom-attributes-to-anchor-html-tag-showdown

@per1234 Please guide, does the information reflects correct use of anchor tags or I'm missing something?

SeppPenner commented 5 years ago

https://daveabrock.com/2018/03/03/using-anchor-links-in-markdown/

This won't apply because it's not markdown but ASCIIDoc?

animeshsrivastava24 commented 5 years ago

Yes @SeppPenner I totally agree with you. And also, I'm confused with anchor tags use. I thought to show their relevance and general use. I guess there might be a possibility that previous comment may lead the discussion to think it was for adoc , I'll surely modify it (thank a lot for this part).