Merge pull request #812 from ipfs/fix/broken-links-669

fix: give relative paths explicit .md suffix so they work in GitHub web UI too [ciskip]

docs/README.md

@@ -10,7 +10,7 @@ description: The home page for developer documentation for IPFS, the InterPlanet
 No matter who you are or what you're creating, you can be part of the movement to create the next generation of the internet. This site contains everything you need to start building using the InterPlanetary File System (IPFS) and pave the way for the future Web.
 :::
 
-Check out some of the most popular content in these docs below — or explore the main site menu to learn about <a href="/concepts/">key concepts</a>, try out <a href="/how-to/">how-to guides</a>, see <a href="/reference/">API and CLI references</a>, or just <a href="/install/">install IPFS</a> and get hacking.
+Check out some of the most popular content in these docs below — or explore the main site menu to learn about [key concepts](concepts/README.md), try out [how-to guides](how-to/README.md), see [API and CLI references](reference/README.md), or just [install IPFS](install/README.md) and get hacking.
 
 ## Download IPFS tools
 
@@ -24,17 +24,17 @@ These tools can help you use and build on IPFS more quickly and efficiently —
 
 Protect yourself from single-point-of-failure risks and benefit from decentralized infrastructure by hosting your static website using IPFS. If you're new to IPFS, this is an excellent place to start learning how to build on the decentralized web.
 
-[Start the tutorial →](/how-to/websites-on-ipfs/single-page-website/)
+[Start the tutorial →](how-to/websites-on-ipfs/single-page-website.md)
 
 ## Learn about the decentralized web
 
 Want to know more about the decentralized web (Dweb) and how it's changing the internet? These resources will give you a clearer understanding of the Dweb movement, and how it's improving the world:
 
-- [What is IPFS](/concepts/what-is-ipfs/)
-- [Peer-to-peer sharing](/concepts/dht/)
-- [Content-addressed data](/concepts/content-addressing/)
+- [What is IPFS](concepts/what-is-ipfs.md)
+- [Peer-to-peer sharing](concepts/dht.md)
+- [Content-addressed data](concepts/content-addressing.md)
 
-[See more guides in the Concepts section →](/concepts/)
+[See more guides in the Concepts section →](concepts/README.md)
 
 ::: callout
 ProtoSchool's self-guided [interactive tutorials](https://proto.school/tutorials) are designed to introduce you to decentralized web concepts, protocols, and tools. Explore js-ipfs APIs by completing browser-based coding challenges in ProtoSchool's [IPFS course](https://proto.school/course/ipfs), or explore code-free intros to essential dweb concepts and related projects in the IPFS ecosystem.
@@ -50,6 +50,6 @@ Are you looking for inspiration? You can find a huge collection of awesome commu
 
 ## Be part of the IPFS community
 
-IPFS has a bustling community of designers, developers, writers, and activists who are all helping to improve the project. You can join in by attending a local meetup, helping out at a conference, chatting online through [Matrix channels](/community/chat), or joining a discussion in [the IPFS forum](https://discuss.ipfs.io/).
+IPFS has a bustling community of designers, developers, writers, and activists who are all helping to improve the project. You can join in by attending a local meetup, helping out at a conference, chatting online through [Matrix channels](community/chat.md), or joining a discussion in [the IPFS forum](https://discuss.ipfs.io/).
 
-[Find out more in the Community section →](/community/)
+[Find out more in the Community section →](community/README.md)

docs/community/README.md

@@ -14,15 +14,15 @@ Sign up for the IPFS Weekly newsletter to get project updates, community news, e
 
 ## Ways to contribute
 
-No matter your area of specialty or level of expertise, there are many [ways to contribute](/community/contribute/ways-to-contribute/) to IPFS and make a real difference in the IPFS community at large.
+No matter your area of specialty or level of expertise, there are many [ways to contribute](contribute/ways-to-contribute.md) to IPFS and make a real difference in the IPFS community at large.
 
 ## IPFS forums
 
 The official [IPFS forums](https://discuss.ipfs.io/) are the primary home of IPFS-related discussion. Join the conversation on [https://discuss.ipfs.io](https://discuss.ipfs.io) for everything from technical questions, project brainstorming, talk on IPFS use cases, and more.
 
 ## Chat
 
-Casual chat fan? Here are [all our channels](/community/chat/). There's getting-started advice for you here, too.
+Casual chat fan? Here are [all our channels](chat.md). There's getting-started advice for you here, too.
 
 ## ProtoSchool workshops
 
@@ -34,7 +34,7 @@ IPFS meetups are also all over the world. [Find one close to you](https://www.me
 
 ## Social media
 
-We're in a lot of places. Here's [how to find them all](social-media) for your favorite platforms.
+We're in a lot of places. Here's [how to find them all](social-media.md) for your favorite platforms.
 
 ## Awesome IPFS
 

docs/community/contribute/contribution-tutorial.md

@@ -5,7 +5,7 @@ description: Learn how to contribute to IPFS documentation through finding issue
 
 # Contribution tutorial
 
-While the [grammar, formatting, and style](/community/contribute/grammar-formatting-and-style/) and the [writing guide](/community/contribute/writing-guide/) can both help you write good content for the IPFS Docs project, they don't delve into _how_ you can submit your content changes. This guide will walk you through finding an issue, fixing it, and then submitting your fix to the `ipfs/ipfs-docs` project.
+While the [grammar, formatting, and style](grammar-formatting-and-style.md) and the [writing guide](writing-guide.md) can both help you write good content for the IPFS Docs project, they don't delve into _how_ you can submit your content changes. This guide will walk you through finding an issue, fixing it, and then submitting your fix to the `ipfs/ipfs-docs` project.
 
 There are plenty of small-sized issues around IPFS documentation that make for easy, helpful contributions to the IPFS project. Here, we'll walk through:
 

docs/community/contribute/grammar-formatting-and-style.md

@@ -5,7 +5,7 @@ description: Learn the syntax and formatting rules for writing documentation for
 
 # Grammar, formatting, and style
 
-This page details the syntax and formatting rules for writing IPFS documentation. For more conceptual ideas of writing, check out the [writing guide](/community/contribute/writing-guide/).
+This page details the syntax and formatting rules for writing IPFS documentation. For more conceptual ideas of writing, check out the [writing guide](writing-guide.md).
 
 ## Grammar and spelling
 
@@ -56,6 +56,10 @@ How the Markdown syntax looks, and code formatting rules to follow.
 
 The IPFS Docs project follows the _GitHub Flavored Markdown_ syntax for markdown. This way, all articles display properly within GitHub itself. This gives readers the option to view articles on [the docs website](https://docs.ipfs.io) or [its GitHub repo](https://github.com/ipfs/ipfs-docs).
 
+#### Relative links
+
+If you include internal (relative) links to other content on the IPFS docs site, please link to them using full relative paths (e.g. use `../` for climbing a directory) and specifying the file's full name (e.g. `awesome-tutorial.md#subheading`). This ensures that users who read docs content directly in-repo on GitHub's web UI are able to follow relative links correctly.
+
 ### Rules
 
 We use the rules set out in the [VSCode Markdownlint](https://github.com/DavidAnson/vscode-markdownlint) extension. You can import these rules into any text editor like Vim or Sublime. All rules are listed [within the Markdownlint repository](https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md).

docs/community/contribute/ways-to-contribute.md

@@ -32,11 +32,11 @@ IPFS is a huge project and undertaking, and with lots of code comes the need for
 
 Before contributing to the IPFS docs, please read these quick guides; they'll save you time and help keep the docs accurate and consistent!
 
-1. [Style and formatting guide](/community/contribute/grammar-formatting-and-style/)
-2. [Writing guide](/community/contribute/writing-guide/)
-3. [Code persona](/community/contribute/code-persona/)
+1. [Style and formatting guide](grammar-formatting-and-style.md)
+2. [Writing guide](writing-guide.md)
+3. [Code persona](code-persona.md)
 
-If you have never contributed to an open-source project before or just need a refresher, take a look at the [contribution tutorial](/community/contribute/contribution-tutorial/).
+If you have never contributed to an open-source project before or just need a refresher, take a look at the [contribution tutorial](contribution-tutorial.md).
 
 ## Support
 

docs/community/contribute/writing-guide.md

@@ -5,7 +5,7 @@ description: Learn the specifics of how to write documentation for the IPFS proj
 
 # Writing guide
 
-This guide explains how to write an article. While the [grammar, formatting, and style guide](/community/contribute/grammar-formatting-and-style/) lets you know the rules you should follow, this guide will help you to properly structure your writing and choose the correct tone for your audience.
+This guide explains how to write an article. While the [grammar, formatting, and style guide](grammar-formatting-and-style.md) lets you know the rules you should follow, this guide will help you to properly structure your writing and choose the correct tone for your audience.
 
 ## Walkthroughs
 

docs/concepts/README.md

@@ -28,57 +28,57 @@ Want the basics in theater mode? Check out these helpful videos for an overview
 
 Get the basic concepts of IPFS in one place, including:
 
-- [What is IPFS?](/concepts/what-is-ipfs/)
-- [How IPFS works](/concepts/how-ipfs-works/)
+- [What is IPFS?](what-is-ipfs.md)
+- [How IPFS works](how-ipfs-works.md)
 - [IPFS primer](https://dweb-primer.ipfs.io/)
-- [Glossary](/concepts/glossary/)
-- [FAQ](/concepts/faq/)
+- [Glossary](glossary.md)
+- [FAQ](faq.md)
 
 ## Examples and case studies
 
 Get inspired by usage ideas, explore examples of IPFS implemented in the wild, and dig deeper with case studies on applications and projects in which IPFS plays a crucial role.
 
-- [Usage ideas & examples](/concepts/usage-ideas-examples/)
-- [Case study: Arbol](/concepts/case-study-arbol/)
-- [Case study: Audius](/concepts/case-study-audius/)
-- [Case study: Fleek](/concepts/case-study-fleek/)
-- [Case study: LikeCoin](/concepts/case-study-likecoin/)
-- [Case study: Morpheus.Network](/concepts/case-study-morpheus/)
-- [Case study: OpenBazaar](/concepts/case-study-openbazaar/)
+- [Usage ideas & examples](usage-ideas-examples.md)
+- [Case study: Arbol](case-study-arbol.md)
+- [Case study: Audius](case-study-audius.md)
+- [Case study: Fleek](case-study-fleek.md)
+- [Case study: LikeCoin](case-study-likecoin.md)
+- [Case study: Morpheus.Network](case-study-morpheus.md)
+- [Case study: OpenBazaar](case-study-openbazaar.md)
 
 ## Content-addressed storage
 
 Referring to files by their content, not their location, is one of the most powerful concepts within IPFS. Learn why with explainers on:
 
-- [Content addressing](/concepts/content-addressing/)
-- [Cryptographic hashing](/concepts/hashing/)
-- [Immutability](/concepts/immutability/)
-- [Persistence, permanence and pinning](/concepts/persistence/)
+- [Content addressing](content-addressing.md)
+- [Cryptographic hashing](hashing.md)
+- [Immutability](immutability.md)
+- [Persistence, permanence and pinning](persistence.md)
 
 ## Peer-to-peer file sharing
 
 Sharing files between peers is incredibly powerful — and has many nuances! Learn about file-sharing paradigms and tools:
 
-- [Distributed Hash Tables (DHTs)](/concepts/dht/)
-- [Merkle DAGs](/concepts/merkle-dag/)
-- [Bitswap](/concepts/bitswap/)
-- [IPLD](/concepts/ipld/)
-- [IPNS](/concepts/ipns/)
-- [libp2p](/concepts/libp2p/)
-- [File systems](/concepts/file-systems/)
+- [Distributed Hash Tables (DHTs)](dht.md)
+- [Merkle DAGs](merkle-dag.md)
+- [Bitswap](bitswap.md)
+- [IPLD](ipld.md)
+- [IPNS](ipns.md)
+- [libp2p](libp2p.md)
+- [File systems](file-systems.md)
 
 ## Integrating IPFS and the existing Web
 
 IPFS aims to be the future of the internet, but it still needs to play well with today's Web. Here are some ways to do just that:
 
-- [IPFS Gateway](/concepts/ipfs-gateway/)
-- [DNSLink](/concepts/dnslink/)
+- [IPFS Gateway](ipfs-gateway.md)
+- [DNSLink](dnslink.md)
 
 ## Further reading
 
-Want a more in-depth look into the decentralized web? Here are a few papers that are useful for understanding IPFS, whether it be understanding the IPFS spec itself or the background for the web, protocols, hashing, and so on. [Read the papers →](/concepts/further-reading/academic-papers)
+Want a more in-depth look into the decentralized web? Here are a few papers that are useful for understanding IPFS, whether it be understanding the IPFS spec itself or the background for the web, protocols, hashing, and so on. [Read the papers →](further-reading/academic-papers.md)
 
-You may also be interested in the community made [IPFS Primer →](https://dweb-primer.ipfs.io/)
+You may also be interested in the community-made [IPFS Primer →](https://dweb-primer.ipfs.io/)
 
 ## Don't see what you're looking for?