docs(all): use remark-validate-links to check internal links, convert to file-path links

.github/workflows/check-links.yml

@@ -0,0 +1,23 @@
+name: Check Markdown links
+
+on:
+  pull_request:
+    branches:
+      - '**'
+
+jobs:
+  markdown-link-check:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3.3.0
+
+    - name: setup node
+      uses: actions/setup-node@64ed1c7eab4cce3362f8c340dee64e5eaeef8f7c # v3.6.0
+      with:
+        cache: 'npm'
+
+    - name: install dependencies
+      run: npm ci
+
+    - name: check internal markdown links
+      run: npm run check-links

docs/components/api.md

@@ -23,35 +23,35 @@ The whole API provided by stencil can be condensed in a set of decorators, lifec
 Decorators are a pure compiler-time construction used by stencil to collect all the metadata about a component, the properties, attributes and methods it might expose, the events it might emit or even the associated stylesheets.
 Once all the metadata has been collected, all the decorators are removed from the output, so they don't incur any runtime overhead.
 
-- [@Component()](component#component-decorator) declares a new web component
-- [@Prop()](properties#prop-decorator) declares an exposed property/attribute
-- [@State()](state#the-state-decorator-state) declares an internal state of the component
-- [@Watch()](reactive-data#watch-decorator) declares a hook that runs when a property or state changes
-- [@Element()](host-element#element-decorator) declares a reference to the host element
-- [@Method()](methods#method-decorator) declares an exposed public method
-- [@Event()](events#event-decorator) declares a DOM event the component might emit
-- [@Listen()](events#listen-decorator) listens for DOM events
+- [@Component()](./component.md#component-decorator) declares a new web component
+- [@Prop()](./properties.md#the-prop-decorator-prop) declares an exposed property/attribute
+- [@State()](./state.md#the-state-decorator-state) declares an internal state of the component
+- [@Watch()](./reactive-data.md#the-watch-decorator-watch) declares a hook that runs when a property or state changes
+- [@Element()](./host-element.md#element-decorator) declares a reference to the host element
+- [@Method()](./methods.md#method-decorator) declares an exposed public method
+- [@Event()](./events.md#event-decorator) declares a DOM event the component might emit
+- [@Listen()](./events.md#listen-decorator) listens for DOM events
 
 
 ## Lifecycle hooks
 
-- [connectedCallback()](component-lifecycle#connectedcallback-)
-- [disconnectedCallback()](component-lifecycle#disconnectedcallback-)
-- [componentWillLoad()](component-lifecycle#componentwillload-)
-- [componentDidLoad()](component-lifecycle#componentdidload-)
-- [componentShouldUpdate(newValue, oldValue, propName): boolean](component-lifecycle#componentshouldupdate)
-- [componentWillRender()](component-lifecycle#componentwillrender-)
-- [componentDidRender()](component-lifecycle#componentdidrender-)
-- [componentWillUpdate()](component-lifecycle#componentwillupdate-)
-- [componentDidUpdate()](component-lifecycle#componentdidupdate-)
-- **[render()](templating-jsx)**
+- [connectedCallback()](./component-lifecycle.md#connectedcallback)
+- [disconnectedCallback()](./component-lifecycle.md#disconnectedcallback)
+- [componentWillLoad()](./component-lifecycle.md#componentwillload)
+- [componentDidLoad()](./component-lifecycle.md#componentdidload)
+- [componentShouldUpdate(newValue, oldValue, propName): boolean](./component-lifecycle.md#componentshouldupdate)
+- [componentWillRender()](./component-lifecycle.md#componentwillrender)
+- [componentDidRender()](./component-lifecycle.md#componentdidrender)
+- [componentWillUpdate()](./component-lifecycle.md#componentwillupdate)
+- [componentDidUpdate()](./component-lifecycle.md#componentdidupdate)
+- **[render()](./templating-and-jsx.md)**
 
 
 ## The appload event
 
 In addition to component-specific lifecycle hooks, a special event called `appload` will be emitted when the app and all of its child components have finished loading. You can listen for it on the `window` object.
 
-If you have multiple apps on the same page, you can determine which app emitted the event by checking `event.detail.namespace`. This will be the value of the [namespace config option](/config#namespace) you've set in your Stencil config.
+If you have multiple apps on the same page, you can determine which app emitted the event by checking `event.detail.namespace`. This will be the value of the [namespace config option](../config/01-overview.md#namespace) you've set in your Stencil config.
 
 ```tsx
 window.addEventListener('appload', (event) => {
@@ -61,17 +61,17 @@ window.addEventListener('appload', (event) => {
 
 ## Other
 
-- [**Host**](host-element): Host is a functional component that can be used at the root of the render function to set attributes and event listeners to the host element itself.
+- [**Host**](./host-element.md): Host is a functional component that can be used at the root of the render function to set attributes and event listeners to the host element itself.
 
-- [**h()**](templating-jsx): It's used within the `render()` to turn the JSX into Virtual DOM elements.
+- [**h()**](./templating-and-jsx.md): It's used within the `render()` to turn the JSX into Virtual DOM elements.
 
 - [**readTask()**](https://developers.google.com/web/fundamentals/performance/rendering/avoid-large-complex-layouts-and-layout-thrashing): Schedules a DOM-read task. The provided callback will be executed in the best moment to perform DOM reads without causing layout thrashing.
 
 - [**writeTask()**](https://developers.google.com/web/fundamentals/performance/rendering/avoid-large-complex-layouts-and-layout-thrashing): Schedules a DOM-write task. The provided callback will be executed in the best moment to perform DOM mutations without causing layout thrashing.
 
 - **forceUpdate()**: Schedules a new render of the given instance or element even if no state changed. Notice `forceUpdate()` is not synchronous and might perform the DOM render in the next frame.
 
-- getAssetPath(): Gets the path to local assets. Refer to the [Assets](/assets#getassetpath) page for usage info.
+- getAssetPath(): Gets the path to local assets. Refer to the [Assets](../guides/assets.md#getassetpath) page for usage info.
 - setMode()
 - getMode()
 - getElement()

docs/components/component-lifecycle.md

@@ -58,7 +58,7 @@ Called once just after the component is fully loaded and the first `render()` oc
 
 ## componentShouldUpdate()
 
-This hook is called when a component's [`Prop`](/properties) or [`State`](/state) property changes and a rerender is about to be requested. This hook receives three arguments: the new value, the old value and the name of the changed state. It should return a boolean to indicate if the component should rerender (`true`) or not (`false`).
+This hook is called when a component's [`Prop`](./properties.md) or [`State`](./state.md) property changes and a rerender is about to be requested. This hook receives three arguments: the new value, the old value and the name of the changed state. It should return a boolean to indicate if the component should rerender (`true`) or not (`false`).
 
 A couple of things to notice is that this method will not be executed before the initial render, that is, when the component is first attached to the dom, nor when a rerender is already scheduled in the next frame.
 

docs/components/component.md

@@ -87,7 +87,7 @@ src/
     └── todo-list.tsx
 ```
 
-Below, the `todo-list` component will correctly load the `sunset.jpg` image from the `assets/` directory, using Stencil's [`getAssetPath()`](/assets#getassetpath).
+Below, the `todo-list` component will correctly load the `sunset.jpg` image from the `assets/` directory, using Stencil's [`getAssetPath()`](../guides/assets.md#getassetpath).
 
 ```tsx
 import { Component, Prop, getAssetPath, h } from '@stencil/core';
@@ -113,9 +113,9 @@ export class TodoList {
 In the example above, the following allows `todo-list` to display the provided asset:
 1. The `TodoList`'s `@Component()` decorator has the `assetsDirs` property, and lists the file's sibling directory, `assets/`.
    This will copy the `assets` directory over to the distribution directory.
-2. Stencil's [`getAssetPath()`](/assets#getassetpath) is used to retrieve the path to the image to be used in the `<img>` tag
+2. Stencil's [`getAssetPath()`](../guides/assets.md#getassetpath) is used to retrieve the path to the image to be used in the `<img>` tag
 
-For more information on configuring assets, please see Stencil's [Assets Guide](/docs/assets)
+For more information on configuring assets, please see Stencil's [Assets Guide](../guides/assets.md)
 
 ### scoped
 
@@ -126,13 +126,13 @@ For more information on configuring assets, please see Stencil's [Assets Guide](
 **Default: `false`**
 
 **Details:**<br/>
-If `true`, the component will use [scoped stylesheets](/docs/styling#scoped-css).
+If `true`, the component will use [scoped stylesheets](./styling.md#scoped-css).
 
-Scoped CSS is an alternative to using the native [shadow DOM](/docs/styling#shadow-dom) style encapsulation.
+Scoped CSS is an alternative to using the native [shadow DOM](./styling.md#shadow-dom) style encapsulation.
 It appends a data attribute to your styles to make them unique and thereby scope them to your component.
 It does not, however, prevent styles from the light DOM from seeping into your component.
 
-To use the native [shadow DOM](/docs/styling#shadow-dom), see the configuration for [`shadow`](#shadow).
+To use the native [shadow DOM](./styling.md#shadow-dom), see the configuration for [`shadow`](#shadow).
 
 This option cannot be set to `true` if `shadow` is enabled.
 
@@ -158,11 +158,11 @@ export class TodoList {
 **Default: `false`**
 
 **Details:**<br/>
-If `true`, the component will use [native Shadow DOM encapsulation](/docs/styling#shadow-dom).
+If `true`, the component will use [native Shadow DOM encapsulation](./styling.md#shadow-dom).
 It will fall back to `scoped` if the browser does not support shadow-dom natively.
 
 `delegatesFocus` is a property that [provides focus](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot/delegatesFocus) to the first focusable entry in a component using Shadow DOM.
-If an object literal containing `delegatesFocus` is provided, the component will use [native Shadow DOM encapsulation](/docs/styling#shadow-dom), regardless of the value assigned to `delegatesFocus`.
+If an object literal containing `delegatesFocus` is provided, the component will use [native Shadow DOM encapsulation](./styling.md#shadow-dom), regardless of the value assigned to `delegatesFocus`.
 
 When `delegatesFocus` is set to `true`, the component will have `delegatesFocus: true` added to its shadow DOM.
 

docs/components/host-element.md

@@ -9,7 +9,7 @@ contributors:
 
 # Working with host elements
 
-Stencil components render their children declaratively in their `render` method [using JSX](templating-jsx). Most of the time, the `render()` function describes the children elements that are about to be rendered, but it can also be used to render attributes of the host element itself.
+Stencil components render their children declaratively in their `render` method [using JSX](./templating-and-jsx.md). Most of the time, the `render()` function describes the children elements that are about to be rendered, but it can also be used to render attributes of the host element itself.
 
 
 ## `<Host>`
@@ -119,7 +119,7 @@ If you need to update the host element in response to prop or state changes, you
 
 ## Styling
 
-See full information about styling on the [Styling page](/styling#shadow-dom-in-stencil).
+See full information about styling on the [Styling page](./styling.md#shadow-dom-in-stencil).
 
 CSS can be applied to the `<Host>` element by using its component tag defined in the `@Component` decorator.
 

docs/components/properties.md

@@ -142,7 +142,7 @@ efficiently re-render your components. Passing a reference to a component as a p
 
 A Prop is by default immutable from inside the component logic. Once a value is set by a user, the component cannot
 update it internally. For more advanced control over the mutability of a prop, please see the 
-[mutable option](properties#prop-mutability-mutable) section of this document.
+[mutable option](#prop-mutability-mutable) section of this document.
 
 ## Types
 
@@ -213,7 +213,7 @@ There are a few ways in which Stencil treats props that are of type `boolean` th
 <todo-list-item is-complete="0"></todo-list-item>
 <todo-list-item is-complete="False"></todo-list-item>
 ```
-3. The value of a boolean prop will be `undefined` if it has no [default value](properties#default-values) and one of
+3. The value of a boolean prop will be `undefined` if it has no [default value](#default-values) and one of
 the following applies:
    1. the prop is not included when using the component
    2. the prop is included when using the component, but is not given a value
@@ -474,7 +474,7 @@ In the first usage of `todo-list-item`, `isComplete` is provided a number value
 receives a string containing "42". The types on `isComplete` reflect the type of the value it was provided, 'number' and
 'string', respectively.
 
-Looking at `label`, it is worth noting that although the prop has a [default value](properties#default-values), it does
+Looking at `label`, it is worth noting that although the prop has a [default value](#default-values), it does
 not narrow the type of `label` to be of type 'string'. In the first usage of `todo-list-item`, `label` is provided a
 value of null, whereas in the second usage it receives a number value of 1. The types of the values stored in `label`
 are correctly reported as 'object' and 'number', respectively.
@@ -518,8 +518,8 @@ When using a Stencil prop that is marked as optional, Stencil will try to infer
 not explicitly given.  In the example above, Stencil is able to understand that:
 
 - `completeMsg` is of type string, because it has an explicit type annotation
-- `label` is of type string, because it has a [default value](properties#default-values) that is of type string
-- `thingToDo` [is of type `any`](properties#any-type), because it has no explicit type annotation, nor default value
+- `label` is of type string, because it has a [default value](#default-values) that is of type string
+- `thingToDo` [is of type `any`](#any-type), because it has no explicit type annotation, nor default value
 
 Because Stencil can infer the type of `label`, the following will fail to compile due to a type mismatch:
 
@@ -645,7 +645,7 @@ export class ToDoListItem {
 
 ## Prop Validation
 
-To do validation of a Prop, you can use the [@Watch()](reactive-data/#watch-decorator) decorator:
+To do validation of a Prop, you can use the [@Watch()](./reactive-data.md#the-watch-decorator-watch) decorator:
 
 ```tsx
 import { Component, Prop, Watch, h } from '@stencil/core';
@@ -723,7 +723,7 @@ This component has **3 properties**, but the compiler will create **only 2 attri
 Notice that the `httpService` type is not a primitive (e.g. not a `number`, `boolean`, or `string`). Since DOM
 attributes can only be strings, it does not make sense to have an associated DOM attribute called `"http-service"`.
 Stencil will not attempt to serialize object-like strings written in HTML into a JavaScript object.
-See [Object Props](properties#object-props) for guidance as to how to configure `httpService`.
+See [Object Props](#object-props) for guidance as to how to configure `httpService`.
 
 At the same time, the `isComplete` & `thingToDo` properties follow 'camelCase' naming, but attributes are 
 case-insensitive, so the attribute names will be `is-complete` & `thing-to-do` by default.
@@ -892,7 +892,7 @@ export class ToDoListItem {
 }
 ```
 
-The component in the example above uses [default values](properties#default-values), and can be used in HTML like so:
+The component in the example above uses [default values](#default-values), and can be used in HTML like so:
 ```html
 <!-- Example of using todo-list-item in HTML -->
 <todo-list-item></todo-list-item>

docs/components/reactive-data.md

@@ -14,7 +14,7 @@ Stencil components update when props or state on a component change.
 
 ## Rendering methods
 
-When a props or state change on a component, the [`render()` method](templating-jsx) is scheduled to run.
+When a props or state change on a component, the [`render()` method](./templating-and-jsx.md) is scheduled to run.
 
 ## The Watch Decorator (`@Watch()`)
 

docs/components/state.md

@@ -91,13 +91,13 @@ export class CurrentTime {
 }
 ```
 
-The example above makes use of the [connectedCallback() lifecycle method](/component-lifecycle#connectedcallback)
+The example above makes use of the [connectedCallback() lifecycle method](./component-lifecycle.md#connectedcallback)
 to set `currentTime` to the value of `Date.now()` every 1000 milliseconds (or, every one second). Because the value of 
 `currentTime` changes every second, Stencil calls the `render` function on `current-time`, which pretty-prints the
 current time.
 
 The example above also makes use of the 
-[disconnectedCallback() lifecycle method](/component-lifecycle#disconnectedcallback) to properly clean up the timer
+[disconnectedCallback() lifecycle method](./component-lifecycle.md#disconnectedcallback) to properly clean up the timer
 that was created using `setInterval` in `connectedCallback()`. This isn't necessary for using `@State`, but is a general
 good practice when using `setInterval`.
 
@@ -153,7 +153,7 @@ export class CurrentTime {
 
 ### Using `@State()` with `@Listen()`
 
-This example makes use of `@State` and [`@Listen`](/events#listen-decorator) decorators. We define a class member
+This example makes use of `@State` and [`@Listen`](./events.md#listen-decorator) decorators. We define a class member
 called `isOpen` and decorate it with `@State()`. With the use of `@Listen()`, we respond to click events toggling the
 value of `isOpen`.
 
@@ -262,7 +262,7 @@ this.items[this.items.length - 1] = newTodo;
 ```
 
 Similar to the examples above, this code sample makes use of the
-[connectedCallback() lifecycle method](/component-lifecycle#connectedcallback) to create a new `Item` and add
+[connectedCallback() lifecycle method](./component-lifecycle.md#connectedcallback) to create a new `Item` and add
 it to `items` every 2000 milliseconds (every two seconds). The example above also makes use of the
-[disconnectedCallback() lifecycle method](/component-lifecycle#disconnectedcallback) to properly clean up the timer
-that was created using `setInterval` in `connectedCallback()`.
+[disconnectedCallback() lifecycle method](./component-lifecycle.md#disconnectedcallback) to properly clean up the timer
+that was created using `setInterval` in `connectedCallback()`.