π A self-hostable personal dashboard built for you. Includes status-checking, widgets, themes, icon packs, a UI editor and tons more!
Vue awesomedashboarddockerhomelabhomepagemitnodejsorganizationproductivitypwaself-hostedstartpagevue
π Writes docs on schema usage for IDE editing
Alicia Sykesc7ef87a32b1d
diff --git a/docs/configuring.md b/docs/configuring.mdindex 92a6bd8f..e09519a0 100644--- a/docs/configuring.md+++ b/docs/configuring.md@@ -49,6 +49,7 @@ The following file provides a reference of all supported configuration options.- [**Notes**](#notes)- [Editing Config through the UI](#editing-config-through-the-ui)- [About YAML](#about-yaml)+ - [Schema Validation in your Editor](#schema-validation-in-your-editor)- [Config Saving Methods](#config-saving-methods)- [Preventing Changes](#preventing-changes)- [Example](#example)@@ -403,6 +404,28 @@ Config can be modified directly through the UI, and then written to disk, or appIf you're new to YAML, it's pretty straight-forward. The format is exactly the same as that of JSON, but instead of using curly braces, structure is denoted using whitespace. This [quick guide](https://linuxhandbook.com/yaml-basics/) should get you up to speed in a few minutes, for more advanced topics take a look at this [Wikipedia article](https://en.wikipedia.org/wiki/YAML).+### Schema Validation in your Editor++Dashy's config is described by a [JSON schema](https://github.com/Lissy93/dashy/blob/master/src/utils/config/ConfigSchema.json) (and served up at `[your-dashy-instance.local]/schema.json`).++Most editors can use this to give you validation, auto-complete and inline docs as you type, so long as you have the `$schema` key pointing to the schema URL.++If you have the [YAML Language Server](https://github.com/redhat-developer/yaml-language-server) in your editor (which comes with the YAML extension), then you can also add the schema directly. E.g. for VS Code, put the following in your `settings.json`.++```json+{+ "yaml.schemas": {+ "https://raw.githubusercontent.com/Lissy93/dashy/master/src/utils/config/ConfigSchema.json": ["conf.yml", "user-data/*.yml"]+ }+}+```++The built-in YAML editor (under Config --> Edit Config) also has live validation and auto-complete from the schema.++<p align="center">+<img width="700" src="https://pixelflare.cc/alicia/dashy/yaml-editor" alt="YAML editor screenshot" />+</p>+### Config Saving MethodsWhen updating the config through the JSON editor in the UI, you have two save options: **Local** or **Write to Disk**.diff --git a/services/endpoints/save-config.js b/services/endpoints/save-config.jsindex a222c37e..448b637e 100644--- a/services/endpoints/save-config.js+++ b/services/endpoints/save-config.js@@ -9,6 +9,30 @@ const path = require('path');const MAX_CONFIG_BYTES = 256 * 1024;+/* Schema modeline, added to conf.yml so editors can validate it (see docs/configuring.md) */+const SCHEMA_MODELINE = '# yaml-language-server: $schema='+ + 'https://raw.githubusercontent.com/Lissy93/dashy/master/src/utils/config/ConfigSchema.json';++// Same shape the YAML language server looks for: '# ' then the directive+const MODELINE = /^#[ \t]+(?:yaml-language-server[ \t]*:|\$schema:).*/m;++/* The document header (comments, blanks, directives) - a modeline is only read from here */+const headerOf = (text) => {+ const lines = String(text).split(/\r?\n/);+ const firstContent = lines.findIndex((line) => !/^\s*(?:#|%|---\s*$|$)/.test(line));+ return (firstContent === -1 ? lines : lines.slice(0, firstContent)).join('\n');+};++/* Saving re-serializes the config, which drops all comments. So carry over the+ * user's modeline (keeping any custom URL), or add the default one to conf.yml */+const withModeline = (newConfig, oldConfig, isRootConfig) => {+ // Nothing to do if it's already there, or if a byte-order-mark must stay first+ if (newConfig.startsWith('\uFEFF') || MODELINE.test(headerOf(newConfig))) return newConfig;+ const [existing] = headerOf(oldConfig).match(MODELINE) || [];+ const modeline = existing || (isRootConfig ? SCHEMA_MODELINE : null);+ return modeline ? `${modeline}\n${newConfig}` : newConfig;+};+// Disallow paths having path separators, control chars (NUL/CR/LF), or ..const SAFE_FILENAME = /^(?!\.+$)[^\\/\0\r\n]+\.ya?ml$/i;@@ -63,7 +87,9 @@ module.exports = async (newConfig, render) => {// Write the new configtry {- await fsPromises.writeFile(targetFilePath, newConfig.config, { encoding: 'utf8' });+ const previous = await fsPromises.readFile(targetFilePath, 'utf8').catch(() => '');+ const toWrite = withModeline(newConfig.config, previous, targetFile === 'conf.yml');+ await fsPromises.writeFile(targetFilePath, toWrite, { encoding: 'utf8' });} catch (error) {respond(false, `Unable to write to ${targetFile}: ${error}`);return;