📔 refactor: docs

- Update examples
- Add new `async` hooks usage examples
- Lint with markdownlint

Author: dr-dimitru

README.md

@@ -48,10 +48,14 @@ FlowRouter.route('/', {
   name: 'index',
   action() {
     // Render a template using Blaze
-    this.render('templateName');
+    this.render('layoutName', 'index');
 
     // Can be used with BlazeLayout,
     // and ReactLayout for React-based apps
+  },
+  waitOn() {
+    // Dynamically load JS per route
+    return [import('/imports/client/index.js')];
   }
 });
 
@@ -67,11 +71,12 @@ FlowRouter.route('*', {
 });
 ```
 
-> NOTE: If you're using TypeScript, FlowRouter supports it. For types to work you need to install and follow the instructions of [zodern:meteor-types](https://github.com/zodern/meteor-types#meteor-apps) if you haven't done it already.
+> [!TIP]
+> If you're using TypeScript, FlowRouter supports it. For types to work you need to install and follow the instructions of [`zodern:meteor-types`](https://github.com/zodern/meteor-types#meteor-apps)
 
 ## Documentation
 
-- Continue with our [wiki](https://github.com/veliovgroup/flow-router/wiki);
+- Continue with our [wiki](https://github.com/veliovgroup/flow-router/wiki) or [README index](https://github.com/veliovgroup/flow-router/blob/master/docs/README.md);
 - [Quick start](https://github.com/veliovgroup/flow-router/blob/master/docs/quick-start.md) tutorial;
 - All docs as [single document](https://github.com/veliovgroup/flow-router/blob/master/docs/full.md).
 
@@ -110,7 +115,7 @@ MONGO_URL="mongodb://127.0.0.1:27017/flow-router-tests" meteor test-packages ./
 
 ### Running Typescript Test
 
-1. Install [tsd](https://github.com/SamVerschueren/tsd) as a global package;
+1. Install [`tsd`](https://github.com/SamVerschueren/tsd) as a global package;
 2. Run `tsd` in your terminal. `tsd` will find the correct `*.test.d.ts` file and return with any errors.
 
 ## Support this project:

docs/README.md

@@ -36,7 +36,8 @@ FlowRouter.route('*', {
 });
 ```
 
-For the new apps it is recommended to set `decodeQueryParamsOnce` to `true`. This flag is here to fix [#78](https://github.com/veliovgroup/flow-router/issues/78). By default it is `false` due to its historical origin for compatibility purposes.
+> [!IMPORTANT]
+> For the new apps it is recommended to set `decodeQueryParamsOnce` to `true`. This flag is here to fix [#78](https://github.com/veliovgroup/flow-router/issues/78). By default it is `false` due to its historical origin for compatibility purposes
 
 ## General tutorials:
 
@@ -46,6 +47,7 @@ For the new apps it is recommended to set `decodeQueryParamsOnce` to `true`. Thi
 - [Templating with Data](https://github.com/veliovgroup/flow-router/blob/master/docs/templating-with-data.md)
 - [Auto-scroll](https://github.com/veliovgroup/flow-router/blob/master/docs/auto-scroll.md)
 - [React.js usage](https://github.com/veliovgroup/flow-router/blob/master/docs/react.md)
+- [Usage in real application](https://github.com/veliovgroup/meteor-files-website/tree/master/imports/client/router)
 
 ## Hooks (*in execution order*):
 
@@ -123,6 +125,9 @@ For the new apps it is recommended to set `decodeQueryParamsOnce` to `true`. Thi
 
 ## Support this project:
 
-This project wouldn't be possible without [ostr.io](https://ostr.io).
-
-Using [ostr.io](https://ostr.io) you are not only [protecting domain names](https://ostr.io/info/domain-names-protection), [monitoring websites and servers](https://ostr.io/info/monitoring), using [Prerendering for better SEO](https://ostr.io/info/prerendering) of your JavaScript website, but support our Open Source activity, and great packages like this one could be available for free.
+- Upload and share files using [☄️ meteor-files.com](https://meteor-files.com/?ref=github-flowrouter-repo-footer) — Continue interrupted file uploads without losing any progress. There is nothing that will stop Meteor from delivering your file to the desired destination
+- Use [▲ ostr.io](https://ostr.io?ref=github-flowrouter-repo-footer) for [Server Monitoring](https://snmp-monitoring.com), [Web Analytics](https://ostr.io/info/web-analytics?ref=github-flowrouter-repo-footer), [WebSec](https://domain-protection.info), [Web-CRON](https://web-cron.info) and [SEO Pre-rendering](https://prerendering.com) of a website
+- Star on [GitHub](https://github.com/veliovgroup/flow-router)
+- Star on [Atmosphere](https://atmospherejs.com/ostrio/flow-router-extra)
+- [Sponsor via GitHub](https://github.com/sponsors/dr-dimitru)
+- [Support via PayPal](https://paypal.me/veliovgroup)

docs/api/README.md

@@ -1,4 +1,4 @@
-# API:
+# API
 
 - __General Methods:__
   - [`.go()` method](https://github.com/veliovgroup/flow-router/blob/master/docs/api/go.md)

docs/api/current.md

@@ -3,12 +3,14 @@
 ```js
 FlowRouter.current();
 ```
- - Returns {*Object*}
+
+- Returns {*Object*}
 
 Get the current state of the router. **This API is not reactive**.
 If you need to watch the changes in the path simply use `FlowRouter.watchPathChange()`.
 
 #### Example
+
 ```js
 // route def: /apps/:appId
 // url: /apps/this-is-my-app?show=yes&color=red
@@ -26,4 +28,5 @@ console.log(current);
 ```
 
 #### Further reading
- - [`.watchPathChange()` method](https://github.com/veliovgroup/flow-router/blob/master/docs/api/watchPathChange.md)
+
+- [`.watchPathChange()` method](https://github.com/veliovgroup/flow-router/blob/master/docs/api/watchPathChange.md)

docs/api/decodeQueryParamsOnce.md

@@ -12,11 +12,13 @@ FlowRouter.decodeQueryParamsOnce = true;
 #### Example
 
 Given the URL in the address bar:
-```
+
+```plain
 http://localhost:3000/signin?after=%2Foauth%2Fauthorize%3Fclient_id%3D123%26redirect_uri%3Dhttps%253A%252F%252Fothersite.com%252F
 ```
 
 If `decodeQueryParamsOnce` is not set or set to `false` ❌ ...
+
 ```js
 FlowRouter.getQueryParam("after");
 // returns: "/oauth/authorize?client_id=123"
@@ -26,6 +28,7 @@ FlowRouter.current().queryParams;
 ```
 
 If `decodeQueryParamsOnce` is set to `true` ✔️ ...
+
 ```js
 FlowRouter.getQueryParam("after");
 // returns: "/oauth/authorize?client_id=123&redirect_uri=https%3A%2F%2Fothersite.com%2F"
@@ -37,5 +40,6 @@ FlowRouter.current().queryParams;
 The former is no longer recommended, but to maintain compatibility with legacy apps, `false` is the default value for this flag. Enabling this flag manually with `true` is recommended for all new apps. For more info, see [#78](https://github.com/veliovgroup/flow-router/issues/78).
 
 #### Further reading
- - [`.getQueryParam()` method](https://github.com/veliovgroup/flow-router/blob/master/docs/api/getQueryParam.md)
- - [`.current()` method](https://github.com/veliovgroup/flow-router/blob/master/docs/api/current.md)
+
+- [`.getQueryParam()` method](https://github.com/veliovgroup/flow-router/blob/master/docs/api/getQueryParam.md)
+- [`.current()` method](https://github.com/veliovgroup/flow-router/blob/master/docs/api/current.md)

docs/api/getParam.md

@@ -3,12 +3,14 @@
 ```js
 FlowRouter.getParam(paramName);
 ```
- - `paramName` {*String*}
- - Returns {*String*}
+
+- `paramName` {*String*}
+- Returns {*String*}
 
 Reactive function which you can use to get a parameter from the URL.
 
 #### Example
+
 ```js
 // route def: /apps/:appId
 // url: /apps/this-is-my-app

docs/api/getQueryParam.md

@@ -3,8 +3,9 @@
 ```js
 FlowRouter.getQueryParam(queryKey);
 ```
- - `queryKey` {*String*}
- - Returns {*String*}
+
+- `queryKey` {*String*}
+- Returns {*String*}
 
 Reactive function which you can use to get a value from the query string.
 

docs/api/getRouteName.md

@@ -3,11 +3,13 @@
 ```js
 FlowRouter.getRouteName();
 ```
- - Returns {*String*}
+
+- Returns {*String*}
 
 Use to get the name of the route reactively.
 
 #### Example
+
 ```js
 Tracker.autorun(function () {
   const routeName = FlowRouter.getRouteName();
@@ -16,4 +18,5 @@ Tracker.autorun(function () {
 ```
 
 #### Further reading
- - [`.current()` method](https://github.com/veliovgroup/flow-router/blob/master/docs/api/current.md)
+
+- [`.current()` method](https://github.com/veliovgroup/flow-router/blob/master/docs/api/current.md)

docs/api/go.md

@@ -1,10 +1,11 @@
 ### go method
 
 `.go(path, params, qs)`
- - `path` {*String*} - Path or Route's name
- - `params` {*Object*} - Serialized route parameters, `{ _id: 'str' }`
- - `qs` {*Object*} - Serialized query string, `{ key: 'val' }`
- - Returns {*true*}
+
+- `path` {*String*} - Path or Route's name
+- `params` {*Object*} - Serialized route parameters, `{ _id: 'str' }`
+- `qs` {*Object*} - Serialized GET-query string, `{ key: 'val' }`
+- Returns {*true*}
 
 ```js
 import { FlowRouter } from 'meteor/ostrio:flow-router-extra';
@@ -19,5 +20,6 @@ FlowRouter.go('blogPost', { _id: 'post_id' }, { commentId: '123' }); // /blog/po
 ```
 
 #### Further reading
- - [`.route()` method](https://github.com/veliovgroup/flow-router/blob/master/docs/api/route.md)
- - [`.getRouteName()` method](https://github.com/veliovgroup/flow-router/blob/master/docs/api/getRouteName.md)
+
+- [`.route()` method](https://github.com/veliovgroup/flow-router/blob/master/docs/api/route.md)
+- [`.getRouteName()` method](https://github.com/veliovgroup/flow-router/blob/master/docs/api/getRouteName.md)

docs/api/group.md

@@ -3,12 +3,13 @@
 Use group routes for better route organization.
 
 `.group(options)`
- - `options` {*Object*} - [Optional]
- - `options.name` {*String*} - [Optional] Route's name
- - `options.prefix` {*String*} - [Optional] Route prefix
- - `options[prop-name]` {*Any*} - [Optional] Any property which will be available inside route call
- - `options[hook-name]` {*Function*} - [Optional] See [all available hooks](https://github.com/veliovgroup/flow-router/tree/master/docs#hooks-in-execution-order)
- - Returns {*Group*}
+
+- `options` {*Object*} - [Optional]
+- `options.name` {*String*} - [Optional] Route's name
+- `options.prefix` {*String*} - [Optional] Route prefix
+- `options[prop-name]` {*Any*} - [Optional] Any property which will be available inside route call
+- `options[hook-name]` {*Function*} - [Optional] See [all available hooks](https://github.com/veliovgroup/flow-router/tree/master/docs#hooks-in-execution-order)
+- Returns {*Group*}
 
 ```js
 const adminRoutes = FlowRouter.group({
@@ -33,6 +34,7 @@ adminRoutes.route('/posts', {
 ```
 
 #### Nested Group
+
 ```js
 const adminRoutes = FlowRouter.group({
     prefix: '/admin',
@@ -51,17 +53,20 @@ superAdminRoutes.route('/post', {
 ```
 
 #### Get group name
+
 ```js
 FlowRouter.current().route.group.name
 ```
 
 This can be useful for determining if the current route is in a specific group (e.g. *admin*, *public*, *loggedIn*) without needing to use prefixes if you don't want to. If it's a nested group, you can get the parent group's name with:
+
 ```js
 FlowRouter.current().route.group.parent.name
 ```
 
 #### Further reading
- - [`.triggersEnter()` hooks](https://github.com/veliovgroup/flow-router/blob/master/docs/hooks/triggersEnter.md)
- - [`.action()` hook](https://github.com/veliovgroup/flow-router/blob/master/docs/hooks/action.md)
- - [`.route()` method](https://github.com/veliovgroup/flow-router/blob/master/docs/api/route.md)
- - [`.current()` method](https://github.com/veliovgroup/flow-router/blob/master/docs/api/current.md)
+
+- [`.triggersEnter()` hooks](https://github.com/veliovgroup/flow-router/blob/master/docs/hooks/triggersEnter.md)
+- [`.action()` hook](https://github.com/veliovgroup/flow-router/blob/master/docs/hooks/action.md)
+- [`.route()` method](https://github.com/veliovgroup/flow-router/blob/master/docs/api/route.md)
+- [`.current()` method](https://github.com/veliovgroup/flow-router/blob/master/docs/api/current.md)

docs/api/onRouteRegister.md

@@ -3,8 +3,9 @@
 ```js
 FlowRouter.onRouteRegister(callback);
 ```
- - `callback` {*Function*}
- - Returns {*void*}
+
+- `callback` {*Function*}
+- Returns {*void*}
 
 This API is specially designed for add-on developers. They can listen for any registered route and add custom functionality to FlowRouter. This works on both server and client alike.
 

docs/api/path.md

@@ -3,10 +3,11 @@
 ```js
 FlowRouter.path(path, params, qs);
 ```
- - `path` {*String*} - Path or Route's name
- - `params` {*Object*} - Serialized route parameters, `{ _id: 'str' }`
- - `qs` {*Object*} - Serialized query string, `{ key: 'val' }`
- - Returns {*String*} - URI
+
+- `path` {*String*} - Path or Route's name
+- `params` {*Object*} - Serialized route parameters, `{ _id: 'str' }`
+- `qs` {*Object*} - Serialized query string, `{ key: 'val' }`
+- Returns {*String*} - URI
 
 ```js
 const pathDef = '/blog/:cat/:id';
@@ -20,4 +21,5 @@ console.log(path); // --> "/blog/met%20eor/abc?show=y%2Be%3Ds&color=black"
 If there are no `params` or `qs`, it will simply return the path as it is.
 
 #### Further reading
- - [`.url()` method](https://github.com/veliovgroup/flow-router/blob/master/docs/api/url.md)
+
+- [`.url()` method](https://github.com/veliovgroup/flow-router/blob/master/docs/api/url.md)

docs/api/pathRegExp.md

@@ -4,11 +4,13 @@
 // Use dashes as separators so `/:id-:slug/` isn't translated to `id-:slug` but to `:id`-`:slug`
 FlowRouter.pathRegExp = /(:[\w\(\)\\\+\*\.\?\[\]]+)+/g;
 ```
- - `pathRegExp` {*RegExp*}
- - Default - `/(:[\w\(\)\\\+\*\.\?\[\]\-]+)+/g`
+
+- `pathRegExp` {*RegExp*}
+- Default - `/(:[\w\(\)\\\+\*\.\?\[\]\-]+)+/g`
 
 Use to change the URI RegEx parser used for `params`, for more info see [#25](https://github.com/veliovgroup/flow-router/issues/25).
 
 #### Further reading
- - [`.route()` method](https://github.com/veliovgroup/flow-router/blob/master/docs/api/route.md)
- - [`.group()` method](https://github.com/veliovgroup/flow-router/blob/master/docs/api/group.md)
+
+- [`.route()` method](https://github.com/veliovgroup/flow-router/blob/master/docs/api/route.md)
+- [`.group()` method](https://github.com/veliovgroup/flow-router/blob/master/docs/api/group.md)

docs/api/refresh.md

@@ -3,22 +3,25 @@
 ```js
 FlowRouter.refresh('layout', 'template');
 ```
- - `layout` {*String*} - [required] Name of the layout template
- - `template` {*String*} - [required] Name of the intermediate template, simple `<template>Loading...</template>` might be a good option
 
+- `layout` {*String*} - [required] Name of the layout template
+- `template` {*String*} - [required] Name of the intermediate template, simple `<template>Loading...</template>` might be a good option
 
 `FlowRouter.refresh()` will force all route's rules and hooks to re-run, including subscriptions, waitOn(s) and template render.
 Useful in cases where template logic depends from route's hooks, example:
+
 ```handlebars
 {{#if currentUser}}
   {{> yield}}
 {{else}}
   {{> loginForm}}
 {{/if}}
 ```
+
 in example above "yielded" template may loose data context after user login action, although user login will cause `yield` template to render - `data` and `waitOn` hooks will not fetch new data.
 
 #### Login example
+
 ```js
 Meteor.loginWithPassword({
   username: '[email protected]'
@@ -37,6 +40,7 @@ Meteor.loginWithPassword({
 ```
 
 #### Logout example
+
 ```js
 Meteor.logout((error) => {
   if (error) {
@@ -48,6 +52,7 @@ Meteor.logout((error) => {
 ```
 
 #### Further reading
- - [`.go()` method](https://github.com/veliovgroup/flow-router/blob/master/docs/api/go.md)
- - [`.route()` method](https://github.com/veliovgroup/flow-router/blob/master/docs/api/route.md)
- - [`.group()` method](https://github.com/veliovgroup/flow-router/blob/master/docs/api/group.md)
+
+- [`.go()` method](https://github.com/veliovgroup/flow-router/blob/master/docs/api/go.md)
+- [`.route()` method](https://github.com/veliovgroup/flow-router/blob/master/docs/api/route.md)
+- [`.group()` method](https://github.com/veliovgroup/flow-router/blob/master/docs/api/group.md)

docs/api/reload.md

@@ -3,11 +3,13 @@
 ```js
 FlowRouter.reload();
 ```
- - Returns {*void*}
+
+- Returns {*void*}
 
 FlowRouter routes are idempotent. That means, even if you call `FlowRouter.go()` to the same URL multiple times, it only activates in the first run. This is also true for directly clicking on paths.
 
 So, if you really need to reload the route, this is the method you want.
 
 #### Further reading
- - [`.refresh()` method](https://github.com/veliovgroup/flow-router/blob/master/docs/api/refresh.md)
+
+- [`.refresh()` method](https://github.com/veliovgroup/flow-router/blob/master/docs/api/refresh.md)

docs/api/render.md

@@ -2,7 +2,8 @@
 
 `this.render()` method is available only [inside hooks](https://github.com/veliovgroup/flow-router/tree/master/docs#hooks-in-execution-order).
 
-- __Note__: `this.render()` method is available only if application has `templating` and `blaze`, or `blaze-html-templates` packages installed.
+> [!NOTE]
+> `this.render()` method is available only if application has `templating` and `blaze`, or `blaze-html-templates` packages installed
 
 #### With Layout