Skip to content

armgit / dashy

Public Imported from GitHub
0

πŸš€ A self-hostable personal dashboard built for you. Includes status-checking, widgets, themes, icon packs, a UI editor and tons more!

πŸ“ Writes docs on schema usage for IDE editing

Alicia Sykesc7ef87a32b1d
diff --git a/docs/configuring.md b/docs/configuring.md
index 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 app
If 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 Methods
When 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.js
index 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 config
try {
- 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;