BHoM / BHoM/documentation

Markdown link strategy

Open
#84 0 comments 0 reactions 2 assignees Claimed by @al-fisher View on GitHub
type:documentation type:feature
Dominant language
C#
Stars
88
Forks
18
Avg merge
6d 19h
Merged PRs (30d)
2

Description

Add the following instructions in the documentation.

## To verify if links between documentation pages are working
- Install Visual Studio Extension: [`Markdown link checker`](https://marketplace.visualstudio.com/items?itemName=dlyz.md-link-checker).
Unlike the Visual Studio Code default md link checker, this link checker extension is able to verify **_relative file links_** (i.e. using relative path from the open md file, pointing to a specific filepath. When linking to a page, its file extension e.g. `.md` must be included in the link).
- CTRL+Shift+P, type `markdown link checker recheck...` and press enter:
![image](https://github.com/BHoM/documentation/assets/6352844/7645340b-d4f8-4793-bef5-9b7598d7b79b)

- Squiggly red line will appear below any broken link. This only works for **_relative file links_** (i.e. using relative path from the open md file, pointing to a specific filepath. When linking to a page, its file extension e.g. `.md` must be included in the link).

## To link to another Markdown file in the Documentation
**General rule: make sure that all Markdown files do not have whitespaces in their filename! Use underscores or dashes instead.**
Otherwise the following won't work (in the URL link, you will need to replace whitespaces with `%20` symbols, or the link checker will not understand the link; in the documentation website the link will still work though).

In Visual Studio Code:
- Open the md file you want to edit.
- In the Explorer, find the file you want to link to.
- Holding Shift, click the file and drag-drop it into the open md file where you want to place a link.
- A link will be created. This link will be a **_relative file link_**, so the `Markdown link checker` extension will be able to verify if the file is findable.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.