Fix inconsistent markdown formatting.

This changes all of the documentation markdown files to follow the same rules. The rules I've applied are from https://github.com/DavidAnson/markdownlint/blob/v0.25.1/doc/Rules.md The reason I felt it was necessary to change all the files was that there were a lot inconsistencies in how the markdown was used. Ranging from header levels to some headers having a new line before content and some not.
2022-08-23 09:57:02 +02:00
parent 99463413b1
commit 2d731d3ed3
23 changed files with 912 additions and 542 deletions
--- a/docs/development-guides.md
+++ b/docs/development-guides.md
@@ -3,6 +3,7 @@
 A series of short tutorials, to guide you through the most common development tasks.

 Sections:
+
 - [Creating a new theme](#creating-a-new-theme)
 - [Writing Translations](#writing-translations)
 - [Adding a new option in the config file](#adding-a-new-option-in-the-config-file)
@@ -17,10 +18,12 @@ Sections:

 Adding a new theme is really easy.  There's two things you need to do: Pass the theme name to Dashy, so that it can be added to the theme selector dropdown menu, and then write some styles!

-##### 1. Add Theme Name
+### 1. Add Theme Name
+
 Choose a snappy name for you're theme, and add it to the `builtInThemes` array inside [`defaults.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js#L27).

-##### 2. Write some Styles!
+### 2. Write some Styles
+
 Put your theme's styles inside [`color-themes.scss`](https://github.com/Lissy93/dashy/blob/master/src/styles/color-themes.scss).
 Create a new block, and make sure that `data-theme` matches the theme name you chose above. For example:

@@ -45,10 +48,12 @@ Dashy is using [vue-i18n](https://vue-i18n.intlify.dev/guide/) to manage multi-l

 Adding a new language is pretty straightforward, with just three steps:

-##### 1. Create a new Language File
+### 1. Create a new Language File
+
 Create a new JSON file in `./src/assets/locales` name is a 2-digit [ISO-639 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) for your language, E.g. for German `de.json`, French `fr.json` or Spanish `es.json` - You can find a list of all ISO codes at [iso.org](https://www.iso.org/obp/ui).

-##### 2. Translate!
+### 2. Translate
+
 Using [`en.json`](https://github.com/Lissy93/dashy/tree/master/src/assets/locales/en.json) as an example, translate the JSON values to your language, while leaving the keys as they are. It's fine to leave out certain items, as if they're missing they will fall-back to English. If you see any attribute which include curly braces (`{xxx}`), then leave the inner value of these braces as is, as this is for variables.

 ```json
@@ -65,7 +70,7 @@ Using [`en.json`](https://github.com/Lissy93/dashy/tree/master/src/assets/locale
 }
 ```

-##### 3. Add your file to the app
+### 3. Add your file to the app

 In [`./src/utils/languages.js`](https://github.com/Lissy93/dashy/tree/master/src/utils/languages.js), you need to do 2 small things:

@@ -73,6 +78,7 @@ First import your new translation file, do this at the top of the page.
 E.g. `import de from '@/assets/locales/de.json';`

 Second, add it to the array of languages, e.g:
+
 ```javascript
 export const languages = [
  {
@@ -89,11 +95,12 @@ export const languages = [
  },
 ];
 ```
+
 You can also add your new language to the readme, under the [Language Switching](https://github.com/Lissy93/dashy#language-switching-) section, and optionally include your name/ username if you'd like to be credited for your work. Done!

 If you are not comfortable with making pull requests, or do not want to modify the code, then feel free to instead send the translated file to me, and I can add it into the application. I will be sure to credit you appropriately.

-# Adding a new option in the config file
+## Adding a new option in the config file

 This section is for, adding a new setting to the config file.

@@ -101,6 +108,7 @@ All of the users config is specified in `./public/conf.yml` - see [Configuring D
 It's important to first ensure that there isn't a similar option already available, the new option is definitely necessary, and most importantly that it is fully backwards compatible.

 Next choose the appropriate section to place it under
+
 - Application settings should be located under `appConfig`
 - Page info (such as text and metadata) should be under `pageInfo`
 - Data relating to specific sections should be under `section[n].displayData`
@@ -132,7 +140,9 @@ For example:
  "example": "0821c65656"
 }
 ```
+
 or
+
 ```json
 "iconSize": {
  "enum": [ "small", "medium", "large" ],
@@ -144,6 +154,7 @@ or
 Finally, add your new property to the [`configuring.md`](./configuring.md) API docs. Put it under the relevant section, and be sure to include field name, data type, a description and mention that it is optional.  If your new feature needs more explaining, then you can also document it under the relevant section elsewhere in the documentation.

 Checklist:
+
 - [ ] Ensure the new attribute is actually necessary, and nothing similar already exists
 - [ ] Update the [Schema](https://github.com/Lissy93/dashy/blob/master/src/utils/ConfigSchema.js) with the parameters for your new option
 - [ ] If required, set a default or fallback value (usually in [`defaults.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js))
@@ -163,12 +174,12 @@ It is important to thoroughly test after any big dependency updates.

 When Dashy is deployed to Netlify, it is effectively running as a static app, and therefore the server-side code for the Node.js endpoints is not available. However Netlify now supports serverless cloud lambda functions, which can be used to replace most functionality.

-#### 1. Run Netlify Dev Server
+### 1. Run Netlify Dev Server

 First off, install the Netlify CLI: `npm install netlify-cli -g`
 Then, from within the root of Dashy's directory, start the server, by running: `netlify dev`

-#### 2. Create a lambda function
+### 2. Create a lambda function

 This should be saved it in the [`./services/serverless-functions`](https://github.com/Lissy93/dashy/tree/master/services/serverless-functions) directory

@@ -179,7 +190,7 @@ exports.handler = async () => ({
 });
 ```

-#### 3. Redirect the Node endpoint to the function
+### 3. Redirect the Node endpoint to the function

 In the [`netlify.toml`](https://github.com/Lissy93/dashy/blob/FEATURE/serverless-functions/netlify.toml) file, add a 301 redirect, with the path to the original Node.js endpoint, and the name of your cloud function

@@ -194,20 +205,23 @@ In the [`netlify.toml`](https://github.com/Lissy93/dashy/blob/FEATURE/serverless
 ---

 ## Hiding Page Furniture on Certain Routes
+
 For some pages (such as the login page, the minimal start page, etc) the basic page furniture, (like header, footer, nav, etc) is not needed. This section explains how you can hide furniture on a new view (step 1), or add a component that should be hidden on certain views (step 2).

-##### 1. Add the route name to the should hide array
+### 1. Add the route name to the should hide array

 In [`./src/utils/defaults.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js), there's an array called `hideFurnitureOn`. Append the name of the route (the same as it appears in [`router.js`](https://github.com/Lissy93/dashy/blob/master/src/router.js)) here.

-##### 2. Add the conditional to the structural component to hide
+### 2. Add the conditional to the structural component to hide

 First, import the helper function:
+
 ```javascript
 import { shouldBeVisible } from '@/utils/SectionHelpers';
 ```

 Then you can create a computed value, that calls this function, passing in the route name:
+
 ```javascript
 export default {
  ...
@@ -221,6 +235,7 @@ export default {
 ```

 Finally, in the markup of your component, just add a `v-if` statement, referencing your computed value
+
 ```vue
 <header v-if="isVisible">
  ...
@@ -230,6 +245,7 @@ Finally, in the markup of your component, just add a `v-if` statement, referenci
 ---

 ## Adding / Using Environmental Variables
+
 All environmental variables are optional. Currently there are not many environmental variables used, as most of the user preferences are stored under `appConfig` in the `conf.yml` file.

 You can set variables either in your environment, or using the [`.env`](https://github.com/Lissy93/dashy/blob/master/.env) file.
@@ -250,12 +266,10 @@ To build a widget, you'll also need some basic knowledge of Vue.js. The [officia

 If you just want to jump straight in, then [here](https://github.com/Lissy93/dashy/commit/3da76ce2999f57f76a97454c0276301e39957b8e) is a complete implementation of a new example widget, or take a look at the [`XkcdComic.vue`](https://github.com/Lissy93/dashy/blob/master/src/components/Widgets/XkcdComic.vue) widget, which is pretty simple.

-
 ### Step 1 - Create Widget

 Firstly, create a new `.vue` file under [`./src/components/Widgets`](https://github.com/Lissy93/dashy/tree/master/src/components/Widgets).

-
 ```vue
 <template>
 <div class="example-wrapper">
@@ -297,14 +311,15 @@ export default {
 ```

 All widgets extend from the [Widget](https://github.com/Lissy93/dashy/blob/master/src/mixins/WidgetMixin.js) mixin. This provides some basic functionality that is shared by all widgets. The mixin includes the following `options`, `startLoading()`, `finishLoading()`, `error()` and `update()`.
+
 - **Getting user options: `options`**
-	- Any user-specific config can be accessed with `this.options.something` (where something is the data key your accessing)
+  - Any user-specific config can be accessed with `this.options.something` (where something is the data key your accessing)
 - **Loading state: `startLoading()` and `finishLoading()`**
-	- You can show the loader with `this.startLoading()`, then when your data request completes, hide it again with `this.finishLoading()`
+  - You can show the loader with `this.startLoading()`, then when your data request completes, hide it again with `this.finishLoading()`
 - **Error handling: `error()`**
-	- If something goes wrong (such as API error, or missing user parameters), then call `this.error()` to show message to user
+  - If something goes wrong (such as API error, or missing user parameters), then call `this.error()` to show message to user
 - **Updating data: `update()`**
-	- When the user clicks the update button, or if continuous updates are enabled, then the `update()` method within your widget will be called
+  - When the user clicks the update button, or if continuous updates are enabled, then the `update()` method within your widget will be called

 ### Step 2 - Adding Functionality

@@ -362,6 +377,7 @@ fetchData() {
 ```

 There are three things happening here:
+
 - If the response completes successfully, we'll pass the results to another function that will handle them
 - If there's an error, then we call `this.error()`, which will show a message to the user
 - Whatever the result, once the request has completed, we call `this.finishLoading()`, which will hide the loader
@@ -398,7 +414,6 @@ Styles can be written your your widget within the `<style>` block.

 There are several color variables used by widgets, which extend from the base pallete. Using these enables users to override colors to theme their dashboard, if they wish. The variables are: `--widget-text-color`, `--widget-background-color` and `--widget-accent-color`

-
 ```vue
 <style scoped lang="scss">
 p.results {
@@ -409,17 +424,18 @@ p.results {

 For examples of finished widget components, see the [Widgets](https://github.com/Lissy93/dashy/tree/master/src/components/Widgets) directory. Specifically, the [`XkcdComic.vue`](https://github.com/Lissy93/dashy/blob/master/src/components/Widgets/XkcdComic.vue) widget is quite minimal, so would make a good example, as will [this example implementation](https://github.com/Lissy93/dashy/commit/3da76ce2999f57f76a97454c0276301e39957b8e).

-
 ### Step 3 - Register

 Next, import and register your new widget, in [`WidgetBase.vue`](https://github.com/Lissy93/dashy/blob/master/src/components/Widgets/WidgetBase.vue). In this file, you'll need to add the following:

 Import your widget file
+
 ```javascript
 import ExampleWidget from '@/components/Widgets/ExampleWidget.vue';
 ```

 Then register the component
+
 ```javascript
 components: {
  ...
@@ -428,6 +444,7 @@ components: {
 ```

 Finally, add the markup to render it. The only attribute you need to change here is, setting `widgetType === 'example'` to your widget's name.
+
 ```vue
 <ExampleWidget
  v-else-if="widgetType === 'example'"
@@ -442,7 +459,6 @@ Finally, add the markup to render it. The only attribute you need to change here

 Finally, add some documentation for your widget in the [Widget Docs](https://github.com/Lissy93/dashy/blob/master/docs/widgets.md), so that others know hoe to use it. Include the following information: Title, short description, screenshot, config options and some example YAML.

-
 **Summary**: For a complete example of everything discussed here, see: [`3da76ce`](https://github.com/Lissy93/dashy/commit/3da76ce2999f57f76a97454c0276301e39957b8e)

 ---
@@ -453,7 +469,8 @@ Any screen that displays part or all of the users config, must not be shown when

 This can be done by checking the `allowViewConfig` attribute of the `permissions` getter, in the store.
 First create a new `computed` property, like:
-```
+
+```javascript
 allowViewConfig() {
  return this.$store.getters.permissions.allowViewConfig;
 },
@@ -463,11 +480,11 @@ Then wrap the part of your UI which displays config with: `v-if="allowViewConfig

 If required, add a message showing that the component isn't available, using the `AccessError` component. E.g.

-```
+```javascript
 import AccessError from '@/components/Configuration/AccessError';
 ```

-```
+```vue
 <AccessError v-else />
 ```