diff --git a/do-doc-updaty-magic.py b/do-doc-updaty-magic.py index ffc1f176..19efcf46 100755 --- a/do-doc-updaty-magic.py +++ b/do-doc-updaty-magic.py @@ -1,12 +1,7 @@ #!/usr/bin/env python3 """ Dashy Documentation Updater for Docusaurus -=========================================== - -This script fetches the latest documentation from the Dashy master branch -and applies all necessary fixes to make it compatible with Docusaurus. - -Usage: python3 update-docs.py +Fetches latest docs from master and applies Docusaurus compatibility fixes. """ import os @@ -15,241 +10,168 @@ import glob import subprocess import sys import shutil -from pathlib import Path -def run_command(cmd, description): - """Run a shell command and return success status""" - print(f"๐Ÿ“‹ {description}...") +def run_cmd(cmd, desc, allow_fail=False): + """Run shell command, return True on success.""" + print(f"๐Ÿ“‹ {desc}...") try: - result = subprocess.run(cmd, shell=True, check=True, capture_output=True, text=True) - print(f"โœ… {description} - SUCCESS") - return True - except subprocess.CalledProcessError as e: - print(f"โŒ {description} - FAILED") - print(f"Error: {e.stderr}") + result = subprocess.run(cmd, shell=True, capture_output=True, text=True) + if result.returncode == 0 or (allow_fail and "Generated static files" in result.stdout): + print(f"โœ… {desc}") + return True + print(f"โŒ {desc}\n{result.stderr}") + return False + except Exception as e: + print(f"โŒ {desc}: {e}") return False def download_docs(): - """Download latest docs from master branch""" - print("๐Ÿš€ Starting Dashy documentation update...") - - # Create temporary directory - if os.path.exists('temp_docs'): - shutil.rmtree('temp_docs') - - # Download docs using git archive - cmd = 'git archive origin/master docs/ | tar -x -C temp_docs --strip-components=0' - if not run_command('mkdir -p temp_docs', 'Create temporary directory'): - return False - - if not run_command('git fetch origin master', 'Fetch latest master branch'): - return False - - if not run_command('git archive origin/master docs/ | tar -x -C temp_docs', 'Download docs from master'): - return False - - # Copy to docs directory - if not run_command('cp -r temp_docs/docs/* docs/', 'Copy docs to current directory'): - return False - - # Clean up + """Download latest docs from master branch.""" + print("๐Ÿš€ Starting documentation update...") shutil.rmtree('temp_docs', ignore_errors=True) + cmds = [ + ('mkdir -p temp_docs', 'Create temp directory'), + ('git fetch origin master', 'Fetch master branch'), + ('git archive origin/master docs/ | tar -x -C temp_docs', 'Download docs'), + ('cp -r temp_docs/docs/* docs/', 'Copy to docs directory'), + ] + for cmd, desc in cmds: + if not run_cmd(cmd, desc): + return False + shutil.rmtree('temp_docs', ignore_errors=True) return True def fix_markdown_file(filepath): - """Apply all Docusaurus compatibility fixes to a single markdown file""" + """Apply Docusaurus compatibility fixes to a markdown file.""" print(f"๐Ÿ”ง Processing: {filepath}") - try: with open(filepath, 'r', encoding='utf-8') as f: - content = f.read() + content = original = f.read() except Exception as e: print(f"โŒ Error reading {filepath}: {e}") return False - original_content = content - - # 1. Remove HTML comments + # Remove HTML comments content = re.sub(r'', '', content, flags=re.DOTALL) - # 2. Replace
with
- content = re.sub(r'', '
', content) - content = re.sub(r'', '
', content) + # Remove

blocks that contain markdown (images, lists) - these break JSX + # Match

...

where content spans multiple lines + content = re.sub(r']*>\s*\n(.*?)\n\s*

', r'\1', content, flags=re.DOTALL) - # 3. Fix unterminated

tags (the main JSX issue we found) - # Remove empty

tags - content = re.sub(r'

\s*\n\s*

', '', content) - content = re.sub(r']*>\s*\n\s*([^<\n]*)\n\s*

', r'\1', content) + # Also remove single-line

wrappers around images + content = re.sub(r']*>\s*(\[?!?\[.*?\].*?)\s*

', r'\1', content) - # Fix specific unterminated

issue in crypto donation section - content = re.sub(r'

\s*\n\s*(\[!\[.*?\].*?\].*?\n)', r'\1', content) + # Fix self-closing tags + content = re.sub(r'', '
', content) + content = re.sub(r'', '

', content) + content = re.sub(r']*[^/])>', r'', content) - # Remove problematic SVG charts that cause JSX errors + # Remove problematic SVG charts content = re.sub(r'\[!\[Stargazers\].*?starchart\.cc.*?\)', '', content, flags=re.DOTALL) content = re.sub(r'\[!\[Contributors\].*?contrib\.rocks.*?\)', '', content, flags=re.DOTALL) - content = re.sub(r'\[!\[Auto-generated contributors\].*?CONTRIBUTORS\.svg.*?\)', '', content, flags=re.DOTALL) - # 4. Remove .md extension from links - content = re.sub(r'\[([^\]]+)\]\(([^)]+)\.md\)', r'[\1](\2)', content) - - # 5. Make links relative - replace ./docs with /docs - content = re.sub(r'\]\(\./docs/', '](/docs/', content) - content = re.sub(r'\]\(\.\./docs/', '](/docs/', content) - - # 6. Fix docs/file.md to /docs/file - content = re.sub(r'\]\(docs/([^)]+)\.md\)', r'](/docs/\1)', content) - - # 7. Fix any remaining .md links and /docs/ prefixes - content = re.sub(r'(/docs/[^)]+)\.md\)', r'\1)', content) - content = re.sub(r'(docs/[^)]+)\.md\)', r'/\1)', content) - - # 8. Critical fix: Convert /docs/ links to relative paths for Docusaurus - # This was the key issue we discovered during testing - content = re.sub(r'\(/docs/([^)]*)\)', r'(/\1)', content) - - # 9. Replace back to top buttons - content = re.sub(r'\[โฌ†๏ธ Back to Top\]\(#[^)]*\)', '**[โฌ†๏ธ Back to Top](#)**', content) - content = re.sub(r'

\s*โฌ†๏ธ Back to Top\s*

', '**[โฌ†๏ธ Back to Top](#)**', content) - - # 10. Remove
tags and convert to headings + # Remove details tags, convert to headings content = re.sub(r']*>\s*([^<]+)\s*', r'### \1\n\n', content) content = re.sub(r'
', '', content) - # 11. Fix GitHub blob links to relative links - content = re.sub(r'https://github\.com/[^/]+/[^/]+/blob/[^/]+/docs/([^)]+)\.md', r'/docs/\1', content) + # Back to top links + content = re.sub(r'\[โฌ†๏ธ Back to Top\]\([^)]*\)', '**[โฌ†๏ธ Back to Top](#)**', content) + content = re.sub(r']*>\s*]*>โฌ†๏ธ Back to Top\s*

', '**[โฌ†๏ธ Back to Top](#)**', content) + + # GitHub blob links to relative content = re.sub(r'https://github\.com/[^/]+/[^/]+/blob/[^/]+/docs/([^)]+)', r'/docs/\1', content) - # 12. Ensure each file has only one main heading - main_headings = re.findall(r'^# .+', content, re.MULTILINE) - if len(main_headings) > 1: - lines = content.split('\n') - first_main_heading_found = False - for i, line in enumerate(lines): - if re.match(r'^# .+', line): - if first_main_heading_found: - lines[i] = '#' + line # Convert # to ## - else: - first_main_heading_found = True - content = '\n'.join(lines) + # Fix links: remove .md extension first + content = re.sub(r'\]\(([^)]+)\.md\)', r'](\1)', content) - # 12. Fix self-closing HTML tags - content = re.sub(r']*[^/])>', r'', content) - content = re.sub(r'', '
', content) - content = re.sub(r'', '
', content) + # Fix relative links - convert ./X and ../X to /docs/X + content = re.sub(r'\]\(\./([^)]+)\)', r'](/docs/\1)', content) + content = re.sub(r'\]\(\.\./([^)]+)\)', r'](/docs/\1)', content) + content = re.sub(r'\]\(docs/([^)]+)\)', r'](/docs/\1)', content) - # 13. Clean up extra whitespace - content = re.sub(r'\n\n\n+', '\n\n', content) - content = content.strip() + # Fix bare links that should be docs (e.g., backup-restore -> /docs/backup-restore) + def fix_doc_link(m): + link = m.group(1) + if link.startswith(('http', '/', '#', 'mailto:')): + return m.group(0) + if '.' in link and not link.endswith(('.md', '.html')): + return m.group(0) + return f'](/docs/{link})' - # 14. Ensure file ends with newline - if not content.endswith('\n'): - content += '\n' + content = re.sub(r'\]\(([^)]+)\)', fix_doc_link, content) - # 15. Special fixes for known problematic files - if 'contributing.md' in filepath: - # Remove problematic SVG contributors chart that causes JSX issues - content = re.sub(r'\[\!\[Auto-generated contributors\].*?\]\([^)]+\)', '', content, flags=re.DOTALL) - # Remove star-gazers chart - content = re.sub(r'### Star-Gazers Over Time.*?$', '', content, flags=re.DOTALL | re.MULTILINE) - # Fix unterminated

tag issue - content = re.sub(r'- \*\*ZEC\*\*: `[^`]+`\s*\n\s*

', lambda m: m.group(0).replace('

', ''), content) + # Clean up any /docs/docs/ that might have been created + content = re.sub(r'/docs/docs/', '/docs/', content) - # Only write if content changed - if content != original_content: + # Cleanup whitespace + content = re.sub(r'\n\n\n+', '\n\n', content).strip() + '\n' + + if content != original: try: with open(filepath, 'w', encoding='utf-8') as f: f.write(content) print(f"โœ… Fixed: {filepath}") - return True except Exception as e: print(f"โŒ Error writing {filepath}: {e}") return False else: - print(f"โ„น๏ธ No changes needed: {filepath}") - return True + print(f"โ„น๏ธ No changes: {filepath}") + return True def process_all_docs(): - """Process all markdown files in the docs directory""" - docs_dir = 'docs' - if not os.path.exists(docs_dir): - print(f"โŒ Error: {docs_dir} directory not found!") + """Process all markdown files in docs directory.""" + if not os.path.exists('docs'): + print("โŒ docs directory not found!") return False - # Find all .md files recursively - md_files = glob.glob(os.path.join(docs_dir, '**', '*.md'), recursive=True) - + md_files = glob.glob('docs/**/*.md', recursive=True) if not md_files: - print(f"โŒ No markdown files found in {docs_dir}") + print("โŒ No markdown files found") return False - print(f"๐Ÿ“š Found {len(md_files)} markdown files to process...") - - success_count = 0 - for md_file in md_files: - if fix_markdown_file(md_file): - success_count += 1 - else: - print(f"โŒ Failed to process {md_file}") - - print(f"\n๐ŸŽ‰ Successfully processed {success_count}/{len(md_files)} files!") - return success_count == len(md_files) + print(f"๐Ÿ“š Found {len(md_files)} markdown files...") + success = sum(1 for f in md_files if fix_markdown_file(f)) + print(f"\n๐ŸŽ‰ Processed {success}/{len(md_files)} files") + return success == len(md_files) def test_build(): - """Test the Docusaurus build""" - print("๐Ÿงช Testing Docusaurus build...") + """Test Docusaurus build.""" + print("๐Ÿงช Testing build...") + run_cmd("pkill -f 'docusaurus start' || true", "Stop dev servers", allow_fail=True) - # Kill any running development servers - run_command("pkill -f 'docusaurus start' || true", "Stop any running dev servers") - - # Test the build - if run_command("npm run build", "Build Docusaurus site"): - print("โœ… Build successful! All documentation is now Docusaurus compatible.") + result = subprocess.run("npm run build", shell=True, capture_output=True, text=True) + if "Generated static files" in result.stdout: + print("โœ… Build successful!") return True - else: - print("โŒ Build failed. There may be remaining compatibility issues.") - return False + print(f"โŒ Build failed\n{result.stderr}") + return False def main(): - """Main function to orchestrate the documentation update""" - print("=" * 60) - print("๐Ÿš€ Dashy Documentation Updater for Docusaurus") - print("=" * 60) + print("=" * 50) + print("๐Ÿš€ Dashy Documentation Updater") + print("=" * 50) - # Check if we're in the right directory - if not os.path.exists('package.json'): - print("โŒ Error: package.json not found. Please run this script from the Docusaurus project root.") - sys.exit(1) - - if not os.path.exists('docusaurus.config.js'): - print("โŒ Error: docusaurus.config.js not found. Please run this script from the Docusaurus project root.") - sys.exit(1) - - steps = [ - ("๐Ÿ“ฅ Download latest docs", download_docs), - ("๐Ÿ”ง Process all markdown files", process_all_docs), - ("๐Ÿงช Test build", test_build) - ] - - for step_name, step_func in steps: - print(f"\n{step_name}") - print("-" * 40) - - if not step_func(): - print(f"\nโŒ FAILED: {step_name}") - print("Please check the errors above and try again.") + for check in ['package.json', 'docusaurus.config.js']: + if not os.path.exists(check): + print(f"โŒ {check} not found - run from project root") sys.exit(1) - print(f"โœ… COMPLETED: {step_name}") + steps = [ + ("Download docs", download_docs), + ("Process markdown", process_all_docs), + ("Test build", test_build), + ] - print("\n" + "=" * 60) - print("๐ŸŽ‰ SUCCESS: Documentation update completed successfully!") - print("=" * 60) - print("\n๐Ÿ“‹ Summary:") - print("โ€ข Downloaded latest docs from master branch") - print("โ€ข Fixed all Docusaurus compatibility issues") - print("โ€ข Verified build works correctly") - print("\n๐Ÿš€ You can now run 'yarn start' to see your updated docs!") + for name, func in steps: + print(f"\n๐Ÿ“ฅ {name}\n" + "-" * 40) + if not func(): + print(f"\nโŒ Failed: {name}") + sys.exit(1) + + print("\n" + "=" * 50) + print("๐ŸŽ‰ Documentation updated successfully!") + print("=" * 50) if __name__ == "__main__": - main() \ No newline at end of file + main() diff --git a/docs/alternate-views.md b/docs/alternate-views.md index 38dac184..5b27b848 100644 --- a/docs/alternate-views.md +++ b/docs/alternate-views.md @@ -14,10 +14,8 @@ You can switch between views using the dropdown in the top-right corner. Set you This is the main page that you will land on when you first launch the application. Here all of your sections (with items + widgets) are visible in a grid layout. -

Example of Default View
Demo -

### Workspace @@ -27,19 +25,15 @@ You can specify a default app to be opened when you land on the workspace, by se You can also opt to keep previously opened websites/ apps open in the background, by setting `appConfig.enableMultiTasking: true`. This comes at the cost of performance, but does mean that your session with each app is preserved, enabling you to quickly switch between them. -

Example of Workspace View
Workspace view demo -

### Minimal View The minimal view aims to be super fast and simple, and can be used as a browser startpage. Items are grouped into a tab view, and the last opened tab will be remembered. Similar to the main view, you can search and launch items just by typing, and right-clicking will show more options (like open in modal, workspace or new tab). -

Example of Minimal View
Workspace view demo -

## Opening Methods @@ -55,10 +49,8 @@ You can also set a default opening method, which will be applied to all items th Even if the target is not set (or is set to `sametab`), you can still launch any given app in an alternative method. Either right-click to see all options, or use one of the keyboard shortcuts: Alt + Click will open the modal, and Ctrl + Click will open in a new tab. -

-

If you don't like the custom context menu, it can be disabled by setting `appConfig.disableContextMenu: true`. -If you get a 'Refused to Connect' error in the modal or workspace views, then the target app has it's X-Frame-Options HTTP set to block requests from embedded content. You can easily fix this by setting this header to ALLOW, for instructions on how to do so, see the [Troubleshooting Docs](/troubleshooting.md#refused-to-connect-in-modal-or-workspace-view). +If you get a 'Refused to Connect' error in the modal or workspace views, then the target app has it's X-Frame-Options HTTP set to block requests from embedded content. You can easily fix this by setting this header to ALLOW, for instructions on how to do so, see the [Troubleshooting Docs](/docs/troubleshooting.md#refused-to-connect-in-modal-or-workspace-view). diff --git a/docs/authentication.md b/docs/authentication.md index 2307dfd0..882261e9 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -115,7 +115,7 @@ pages: Any user who is not an admin (with `type: admin`) will not be able to write changes to disk. -You can also prevent any user from writing changes to disk, using `preventWriteToDisk`. Or prevent any changes from being saved locally in browser storage, using `preventLocalSave`. Both properties can be found under [`appConfig`](/configuring.md#appconfig-optional). +You can also prevent any user from writing changes to disk, using `preventWriteToDisk`. Or prevent any changes from being saved locally in browser storage, using `preventLocalSave`. Both properties can be found under [`appConfig`](/docs/configuring.md#appconfig-optional). To disable all UI config features, including View Config, set `disableConfiguration`. Alternatively you can disable UI config features for all non admin users by setting `disableConfigurationForNonAdmin` to true. @@ -246,7 +246,7 @@ sections: groups: ['DevelopmentTeam'] ``` -Depending on how you're hosting Dashy and Keycloak, you may also need to set some HTTP headers, to prevent a CORS error. This would typically be the `Access-Control-Allow-Origin [URL-of Dashy]` on your Keycloak instance. See the [Setting Headers](/docs/management#setting-headers) guide in the management docs for more info. +Depending on how you're hosting Dashy and Keycloak, you may also need to set some HTTP headers, to prevent a CORS error. This would typically be the `Access-Control-Allow-Origin [URL-of Dashy]` on your Keycloak instance. See the [Setting Headers](/docs/management.md#setting-headers) guide in the management docs for more info. Your app is now secured :) When you load Dashy, it will redirect to your Keycloak login page, and any user without valid credentials will be prevented from accessing your dashboard. diff --git a/docs/backup-restore.md b/docs/backup-restore.md index 8a8228b0..36c71e09 100644 --- a/docs/backup-restore.md +++ b/docs/backup-restore.md @@ -1,14 +1,12 @@ # Cloud Backup and Restore -Beyond the cloud backup/restore service, there are several other self-hosted options you can use to backup Dashy, and any other Docker container data. These are outlined in the Management docs, at: [Docker Backup Options](/management.md#backing-up). +Beyond the cloud backup/restore service, there are several other self-hosted options you can use to backup Dashy, and any other Docker container data. These are outlined in the Management docs, at: [Docker Backup Options](/docs/management.md#backing-up). Dashy has a built-in feature for securely backing up your config to a hosted cloud service, and then restoring it on another instance. This feature is totally optional, and if you do not enable it, then Dashy will not make any external network requests. This is useful not only for backing up your configuration off-site, but it also enables Dashy to be used without having write a YAML config file, and makes it possible to use a public hosted instance, without the need to self-host. -

-

## How it Works diff --git a/docs/configuring.md b/docs/configuring.md index e812fd5f..a4d5a8dc 100644 --- a/docs/configuring.md +++ b/docs/configuring.md @@ -18,7 +18,7 @@ All app configuration is specified in [`/user-data/conf.yml`](https://github.com - You may find it helpful to look at some sample config files to get you started, a collection of which can be found [here](https://gist.github.com/Lissy93/000f712a5ce98f212817d20bc16bab10) - You can check that your config file fits the schema, by running `yarn validate-config` - After modifying your config, the app needs to be recompiled, by running `yarn build` - this happens automatically if you're using Docker -- It is recommended to keep a backup of your config file. You can download it under Config menu, or use the [Cloud Backup](/backup-restore) feature. +- It is recommended to keep a backup of your config file. You can download it under Config menu, or use the [Cloud Backup](/docs/backup-restore) feature. - You can make use of YAML features, like anchors, comments, multi-line strings, etc to reuse attributes and keep your config file readable - Once you have finished configuring your dashboard, you can choose to [disable UI config](#preventing-changes) if you wish - All fields are optional, unless otherwise stated. @@ -95,7 +95,7 @@ The following file provides a reference of all supported configuration options. **`name`** | `string` | Required | A unique name for that page **`path`** | `string` | Required | The path (local or remote) to the config file to use.
For files located within `/user-data`, you only need to specify filename, for externally hosted files you must include the full URL -For more info, see the[Multi-Page docs](/pages-and-sections.md#multi-page-support) +For more info, see the[Multi-Page docs](/docs/pages-and-sections.md#multi-page-support) ****[โฌ†๏ธ Back to Top](#)**** @@ -113,15 +113,15 @@ For more info, see the[Multi-Page docs](/pages-and-sections.md#multi-page-suppor **`enableFontAwesome`** | `boolean` | _Optional_ | If set to `true` font-awesome will be loaded, if set to `false` they will not be. if left blank font-awesome will be enabled only if required by 1 or more icons **`enableMaterialDesignIcons`** | `boolean` | _Optional_ | If set to `true` mdi icons will be loaded, if set to `false` they will not be. Where `true` is enabled, if left blank material design icons will be enabled only if required by 1 or more icons **`fontAwesomeKey`** | `string` | _Optional_ | If you have a font-awesome key, then you can use it here and make use of premium icons. It is a 10-digit alpha-numeric string from you're FA kit URL (e.g. `13014ae648`) -**`faviconApi`** | `enum` | _Optional_ | Only applicable if you are using favicons for item icons. Specifies which service to use to resolve favicons. Set to `local` to do this locally, without using an API. Services running locally will use this option always. Available options are: `local`, `faviconkit`, `iconhorse`, `google`, `clearbit`, `webmasterapi` and `allesedv`. Defaults to `faviconkit`. See [Icons](/icons.md#favicons) for more info +**`faviconApi`** | `enum` | _Optional_ | Only applicable if you are using favicons for item icons. Specifies which service to use to resolve favicons. Set to `local` to do this locally, without using an API. Services running locally will use this option always. Available options are: `local`, `faviconkit`, `iconhorse`, `google`, `clearbit`, `webmasterapi` and `allesedv`. Defaults to `faviconkit`. See [Icons](/docs/icons.md#favicons) for more info **`auth`** | `object` | _Optional_ | All settings relating to user authentication. See [`auth`](#appconfigauth-optional) -**`defaultIcon`** | `string` | _Optional_ | An icon to be applied to any items, which don't already have an icon set. See [Icon Docs](/icons.md#default-icon) for more info +**`defaultIcon`** | `string` | _Optional_ | An icon to be applied to any items, which don't already have an icon set. See [Icon Docs](/docs/icons.md#default-icon) for more info **`layout`** | `enum` | _Optional_ | Layout for homepage, either `horizontal`, `vertical` or `auto`. Defaults to `auto`. This specifies the layout and direction of how sections are positioned on the home screen. This can also be modified and overridden from the UI. **`iconSize`** | `enum` | _Optional_ | The size of link items / icons. Can be either `small`, `medium,` or `large`. Defaults to `medium`. This can also be set directly from the UI. **`colCount`** | `number` | _Optional_ | The number of columns of sections displayed on the homepage, using the default view. Should be in integer between `1` and `8`. Note that by default this is applied responsively, based on current screen size, and specifying a value here will override this behavior, which may not be desirable. **`theme`** | `string` | _Optional_ | The default theme for first load (you can change this later from the UI) **`cssThemes`** | `string[]` | _Optional_ | An array of custom theme names which can be used in the theme switcher dropdown -**`customColors`** | `object`| _Optional_ | Enables you to apply a custom color palette to any given theme. Use the theme name (lowercase) as the key, for an object including key-value-pairs, with the color variable name as keys, and 6-digit hex code as value. See [Theming](/theming.md#modifying-theme-colors) for more info +**`customColors`** | `object`| _Optional_ | Enables you to apply a custom color palette to any given theme. Use the theme name (lowercase) as the key, for an object including key-value-pairs, with the color variable name as keys, and 6-digit hex code as value. See [Theming](/docs/theming.md#modifying-theme-colors) for more info **`externalStyleSheet`** | `string` or `string[]` | _Optional_ | Either a URL to an external stylesheet or an array or URLs, which can be applied as themes within the UI **`customCss`** | `string` | _Optional_ | Raw CSS that will be applied to the page. This can also be set from the UI. Please minify it first. **`hideComponents`** | `object` | _Optional_ | A list of key page components (header, footer, search, settings, etc) that are present by default, but can be removed using this option. See [`appConfig.hideComponents`](#appconfighideComponents-optional) @@ -151,11 +151,11 @@ For more info, see the[Multi-Page docs](/pages-and-sections.md#multi-page-suppor > [!WARNING] > Built-in auth should **not be used** for security-critical applications, or if your Dashy instance is publicly accessible. -> For these, it is recommended to use an [alternate authentication method](/authentication.md#alternative-authentication-methods). +> For these, it is recommended to use an [alternate authentication method](/docs/authentication.md#alternative-authentication-methods). **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- -**`users`** | `array` | _Optional_ | An array of objects containing usernames and hashed passwords. If this is not provided, then authentication will be off by default, and you will not need any credentials to access the app. See [`appConfig.auth.users`](#appconfigauthusers-optional).
**Note** this method of authentication is handled on the client side, so for security critical situations, it is recommended to use an [alternate authentication method](/authentication.md#alternative-authentication-methods). +**`users`** | `array` | _Optional_ | An array of objects containing usernames and hashed passwords. If this is not provided, then authentication will be off by default, and you will not need any credentials to access the app. See [`appConfig.auth.users`](#appconfigauthusers-optional).
**Note** this method of authentication is handled on the client side, so for security critical situations, it is recommended to use an [alternate authentication method](/docs/authentication.md#alternative-authentication-methods). **`enableKeycloak`** | `boolean` | _Optional_ | If set to `true`, then authentication using Keycloak will be enabled. Note that you need to have an instance running, and have also configured `auth.keycloak`. Defaults to `false` **`keycloak`** | `object` | _Optional_ | Config options to point Dashy to your Keycloak server. Requires `enableKeycloak: true`. See [`auth.keycloak`](#appconfigauthkeycloak-optional) for more info **`enableHeaderAuth`** | `boolean` | _Optional_ | If set to `true`, then authentication using HeaderAuth will be enabled. Note that you need to have your web server/reverse proxy running, and have also configured `auth.headerAuth`. Defaults to `false` @@ -164,7 +164,7 @@ For more info, see the[Multi-Page docs](/pages-and-sections.md#multi-page-suppor **`oidc`** | `object` | _Optional_ | Config options to point Dash to your OIDC configuration. Request `enableOidc: true`. See [`auth.oidc`](#appconfigauthoidc-optional) for more info **`enableGuestAccess`** | `boolean` | _Optional_ | When set to `true`, an unauthenticated user will be able to access the dashboard, with read-only access, without having to login. Requires `auth.users` to be configured. Defaults to `false`. -For more info, see the **[Authentication Docs](/authentication)** +For more info, see the **[Authentication Docs](/docs/authentication)** ****[โฌ†๏ธ Back to Top](#)**** @@ -287,10 +287,10 @@ For more info, see the **[Authentication Docs](/authentication)** **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- -**`type`** | `string` | Required | The widget type. See [Widget Docs](/widgets) for full list of supported widgets -**`options`** | `object` | _Optional_ | Some widgets accept either optional or required additional options. Again, see the [Widget Docs](/widgets) for full list of options -**`updateInterval`** | `number` | _Optional_ | You can keep a widget constantly updated by specifying an update interval, in seconds. See [Continuous Updates Docs](/widgets.md#continuous-updates) for more info -**`useProxy`** | `boolean` | _Optional_ | Some widgets make API requests to services that are not CORS-enabled. For these instances, you will need to route requests through a proxy, Dashy has a built in CORS-proxy, which you can use by setting this option to `true`. Defaults to `false`. See the [Proxying Requests Docs](/widgets.md#proxying-requests) for more info +**`type`** | `string` | Required | The widget type. See [Widget Docs](/docs/widgets) for full list of supported widgets +**`options`** | `object` | _Optional_ | Some widgets accept either optional or required additional options. Again, see the [Widget Docs](/docs/widgets) for full list of options +**`updateInterval`** | `number` | _Optional_ | You can keep a widget constantly updated by specifying an update interval, in seconds. See [Continuous Updates Docs](/docs/widgets.md#continuous-updates) for more info +**`useProxy`** | `boolean` | _Optional_ | Some widgets make API requests to services that are not CORS-enabled. For these instances, you will need to route requests through a proxy, Dashy has a built in CORS-proxy, which you can use by setting this option to `true`. Defaults to `false`. See the [Proxying Requests Docs](/docs/widgets.md#proxying-requests) for more info **`timeout`** | `number` | _Optional_ | Request timeout in milliseconds, defaults to ยฝ a second (`500`) **`ignoreErrors`** | `boolean` | _Optional_ | Prevent an error message being displayed, if a network request or something else fails. Useful for false-positives **`label`** | `string` | _Optional_ | Add custom label to a given widget. Useful for identification, if there are multiple of the same type of widget in a single section @@ -324,7 +324,7 @@ For more info, see the **[Authentication Docs](/authentication)** **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- -**`icon`** | `string` | _Optional_ | The icon for a given item or section.
See [Icon Docs](/icons) for all available supported icon types, including: auto-fetched favicons, generative icons, emoji icons, home-lab service logos, font-awesome, simple-icons, material icons, selfh.st icons, and icons specified by URL +**`icon`** | `string` | _Optional_ | The icon for a given item or section.
See [Icon Docs](/docs/icons) for all available supported icon types, including: auto-fetched favicons, generative icons, emoji icons, home-lab service logos, font-awesome, simple-icons, material icons, selfh.st icons, and icons specified by URL ****[โฌ†๏ธ Back to Top](#)**** @@ -345,7 +345,6 @@ For more info, see the **[Authentication Docs](/authentication)** Config can be modified directly through the UI, and then written to disk, or applied locally. This can be done wither with the raw config editor (introduced in V 0.6.5 / [#3](https://github.com/Lissy93/dashy/pull/3)), or the interactive editor (introduced in V 1.8.9 / [#298](https://github.com/Lissy93/dashy/pull/298)). -

Interactive Editor
Interactive Editor demo @@ -355,7 +354,6 @@ Config can be modified directly through the UI, and then written to disk, or app JSON Editor
Config Editor demo -

### About YAML diff --git a/docs/contributing.md b/docs/contributing.md index 50a12705..433be47a 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -2,7 +2,7 @@ First off, thank you for considering contributing towards Dashy! ๐Ÿ™Œ There are several ways that you can help out, and any contributions, however small will always be very much appreciated. -You will be appropriately credited in the readme - huge thank you to [everyone who has helped](/credits) so far ๐Ÿ’ž +You will be appropriately credited in the readme - huge thank you to [everyone who has helped](/docs/credits) so far ๐Ÿ’ž ## Take a 2-minute survey @@ -12,7 +12,7 @@ Help improve Dashy by taking a very short, 6-question survey. This will give me ## Share your dashboard -Dashy now has a [Showcase](/docs/showcase#dashy-showcase-) where you can show off a screenshot of your dashboard, and get inspiration from other users (and I really love seeing how people are using Dashy). To [submit your dashboard](/docs/showcase#submitting-your-dashboard), either open a PR or raise an issue. +Dashy now has a [Showcase](/docs/showcase.md#dashy-showcase-) where you can show off a screenshot of your dashboard, and get inspiration from other users (and I really love seeing how people are using Dashy). To [submit your dashboard](/docs/showcase.md#submitting-your-dashboard), either open a PR or raise an issue. [![Add your Dashboard to the Showcase](https://img.shields.io/badge/Add_your_Dashboard-Showcase-%238616ee?style=for-the-badge&logo=feathub&logoColor=8616ee)](https://github.com/Lissy93/dashy/issues/new?assignees=&labels=%F0%9F%92%AF+Showcase&template=showcase-addition.yml&title=%5BSHOWCASE%5D+%3Ctitle%3E) @@ -35,8 +35,6 @@ Sponsoring will give you several perks - for $1 / ยฃ0.75 per month, you'll get a - **LTC**: `MAuck6Ea1qaNihwKfXutkR1R6BorMth86H` - **ZEC**: `t1bw1SefijsXRDQVxC9w64XsRK8hBhtQohQ` - - ## Enable Anonymous Bug Reports Bug reports helps me to discover bugs I was unaware of, and then fix them, in order to make Dashy more reliable long term. This is a simple, yet really helpful step you can take to help improve Dashy. [Sentry](https://github.com/getsentry/sentry) is an open source error tracking and performance monitoring tool, which enables the identification any errors which occur in the production app (only if you enable it). @@ -56,7 +54,7 @@ If you speak another language, then adding translations will help make Dashy ava ## Submit a PR -Contributing to the code or docs is super helpful. You can fix a bug, add a new feature or improve an existing one. If you've built your own custom widget, theme or view, consider sharing it in a PR. I've written [several guides](/development-guides) to help you get started, and the steps for setting up the development environment are outlined in the [Development Docs](/developing). Feel free to ask if you have any questions. +Contributing to the code or docs is super helpful. You can fix a bug, add a new feature or improve an existing one. If you've built your own custom widget, theme or view, consider sharing it in a PR. I've written [several guides](/docs/development-guides) to help you get started, and the steps for setting up the development environment are outlined in the [Development Docs](/docs/developing). Feel free to ask if you have any questions. ## Improve the Docs @@ -124,10 +122,10 @@ If you like, you could also consider [subscribing to my mailing list](https://no ### Contributors -For a full list of Dashy's contributors, see the [Credits Page](/credits) - -](/docs/credits) +For a full list of Dashy's contributors, see the [Credits Page](/docs/credits) +[![Auto-generated contributors](https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/CONTRIBUTORS.svg)](/docs/credits) +### Star-Gazers Over Time ](https://seladb.github.io/StarTrack-js/#/preload?r=Lissy93,dashy) diff --git a/docs/credits.md b/docs/credits.md index 428f9cc5..c6555f6e 100644 --- a/docs/credits.md +++ b/docs/credits.md @@ -47,4 +47,4 @@ At it's core, the application uses [**Vue.js**](https://github.com/vuejs/vue), a ## You -Would you like to be listed here? Whatever your skill set, Dashy needs people like you to help support future development. Check out the [Contributing Page](/contributing) for ways that you can get involved. Huge thank you to everyone who has already contributed! ๐Ÿ’– +Would you like to be listed here? Whatever your skill set, Dashy needs people like you to help support future development. Check out the [Contributing Page](/docs/contributing) for ways that you can get involved. Huge thank you to everyone who has already contributed! ๐Ÿ’– diff --git a/docs/deployment.md b/docs/deployment.md index 5f2279ec..925feb06 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -4,15 +4,15 @@ Welcome to Dashy, so glad you're here :) Deployment is super easy, and there are ## Quick Start -If you want to skip the fuss, and [get straight down to it](/quick-start), then you can spin up a new instance of Dashy by running: +If you want to skip the fuss, and [get straight down to it](/docs/quick-start), then you can spin up a new instance of Dashy by running: ```bash docker run -p 8080:8080 lissy93/dashy ``` -See [Management Docs](/management) for info about securing, monitoring, updating, health checks, auto starting, web server configuration, etc +See [Management Docs](/docs/management) for info about securing, monitoring, updating, health checks, auto starting, web server configuration, etc -Once you've got Dashy up and running, you'll want to configure it with your own content, for this you can reference the [configuring docs](/configuring). +Once you've got Dashy up and running, you'll want to configure it with your own content, for this you can reference the [configuring docs](/docs/configuring). ## Deployment Methods @@ -367,7 +367,7 @@ Minimum 526mb mem, 2GB disk space. ### CDN / Cloud Deploy -No specific requirements. The built application alone (without the Node server) is very light-weight, and can be handled smoothly by pretty much any CDN or cloud deployment service (see [this list](/deployment.md#deploy-to-cloud-service) or natively supported cloud providers). +No specific requirements. The built application alone (without the Node server) is very light-weight, and can be handled smoothly by pretty much any CDN or cloud deployment service (see [this list](/docs/deployment.md#deploy-to-cloud-service) or natively supported cloud providers). If you're using your own icons, or other assets, additional disk space will be required for those resources. diff --git a/docs/developing.md b/docs/developing.md index a3648c0b..e5a2ed74 100644 --- a/docs/developing.md +++ b/docs/developing.md @@ -1,7 +1,7 @@ # Developing This article outlines how to get Dashy running in a development environment, and outlines the basics of the architecture. -If you're adding new features, you may want to check out the [Development Guides](/development-guides) docs, for tutorials covering basic tasks. +If you're adding new features, you may want to check out the [Development Guides](/docs/development-guides) docs, for tutorials covering basic tasks. - [Setting up the Development Environment](#setting-up-the-dev-environment) - [Prerequisites](#prerequisites) diff --git a/docs/development-guides.md b/docs/development-guides.md index 29838848..c74edb9b 100644 --- a/docs/development-guides.md +++ b/docs/development-guides.md @@ -34,15 +34,15 @@ html[data-theme='tiger'] { } ``` -Then you can go ahead and write your own custom CSS. Although all CSS is supported here, the best way to define your theme is by setting the CSS variables. You can find a [list of all CSS variables, here](/docs/theming#css-variables). +Then you can go ahead and write your own custom CSS. Although all CSS is supported here, the best way to define your theme is by setting the CSS variables. You can find a [list of all CSS variables, here](/docs/theming.md#css-variables). -For a full guide on styling, see [Theming Docs](./theming). +For a full guide on styling, see [Theming Docs](/docs/theming). -Note that if your theme is just for yourself, and you're not submitting a PR, then you can instead just pass it under `appConfig.cssThemes` inside your config file. And then put your theme in your own stylesheet, and pass it into the Docker container - [see how](/docs/theming#adding-your-own-theme). +Note that if your theme is just for yourself, and you're not submitting a PR, then you can instead just pass it under `appConfig.cssThemes` inside your config file. And then put your theme in your own stylesheet, and pass it into the Docker container - [see how](/docs/theming.md#adding-your-own-theme). ## Writing Translations -For full docs about Dashy's multi-language support, see [Multi-Language Support](./multi-language-support) +For full docs about Dashy's multi-language support, see [Multi-Language Support](/docs/multi-language-support) Dashy is using [vue-i18n](https://vue-i18n.intlify.dev/guide/) to manage multi-language support. @@ -104,7 +104,7 @@ If you are not comfortable with making pull requests, or do not want to modify t This section is for, adding a new setting to the config file. -All of the users config is specified in `./user-data/conf.yml` - see [Configuring Docs](./configuring) for info. +All of the users config is specified in `./user-data/conf.yml` - see [Configuring Docs](/docs/configuring) for info. 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 @@ -151,14 +151,14 @@ or } ``` -Finally, add your new property to the [`configuring.md`](./configuring) 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 explanation, then you can also document it under the relevant section elsewhere in the documentation. +Finally, add your new property to the [`configuring.md`](/docs/configuring) 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 explanation, 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)) -- [ ] Document the new value in [`configuring.md`](./configuring), and if required under the relevant section in the docs +- [ ] Document the new value in [`configuring.md`](/docs/configuring), and if required under the relevant section in the docs - [ ] Ensure your changes are backwards compatible, and that nothing breaks if the attribute isn't specified --- diff --git a/docs/icons.md b/docs/icons.md index 67ef94fd..1a2ee2aa 100644 --- a/docs/icons.md +++ b/docs/icons.md @@ -15,9 +15,7 @@ Both sections and items can have an icon, which is specified using the `icon` at - [Using a Default Icon](#default-icon) - [No Icon](#no-icon) -

-

--- @@ -25,9 +23,7 @@ Both sections and items can have an icon, which is specified using the `icon` at Dashy can auto-fetch an icon for a given service, using it's favicon. Just set `icon: favicon` to use this feature. -

-

Since different websites host their favicons at different paths, for the best results Dashy can use an API to resolve a websites icon. @@ -56,9 +52,7 @@ You can use any [Font Awesome Icon](https://fontawesome.com/icons) simply by spe Font-Awesome has a wide variety of free icons, but you can also use their pro icons if you have a membership. To do so, you need to specify your license key under: `appConfig.fontAwesomeKey`. This is usually a 10-digit string, for example `13014ae648`. -

-

--- @@ -66,9 +60,7 @@ Font-Awesome has a wide variety of free icons, but you can also use their pro ic [SimpleIcons.org](https://simpleicons.org/) is a collection of 2000+ high quality, free and open source brand and logo SVG icons. Usage of which is very similar to font-awesome icons. First find the glyph you want to use on the [website](https://simpleicons.org/), then just set your icon to the simple icon slug, prefixed with `si-`. -

-

For example: @@ -92,9 +84,7 @@ sections: To uses a unique and programmatically generated icon for a given service just set `icon: generative`. This is particularly useful when you have a lot of similar services with a different IP or port, and no specific icon. These icons are generated with [DiceBear](https://api.dicebear.com/) (or [Evatar](https://evatar.io/) for fallback), and use a hash of the services domain/ ip for entropy, so each domain will have a unique icon. -

-

--- @@ -102,9 +92,7 @@ To uses a unique and programmatically generated icon for a given service just se You can use almost any emoji as an icon for items or sections. You can specify the emoji either by pasting it directly, using it's unicode ( e.g. `'U+1F680'`) or shortcode (e.g. `':rocket:'`). You can find these codes for any emoji using [Emojipedia](https://emojipedia.org/) (near the bottom of emoji each page), or for a quick reference to emoji shortcodes, check out [emojis.ninja](https://emojis.ninja/) by @nomanoff. -

-

For example, these will all render the same rocket (๐Ÿš€) emoji: `icon: ':rocket:'` or `icon: 'U+1F680'` or `icon: ๐Ÿš€` @@ -116,9 +104,7 @@ The [selfh.st](https://selfh.st/) project provides a set of icons, originally fo Note: These icons are fetched from the jsdelivr CDN, so if you require offline access, the [Local Icons](#local-icons) method may be a better option for you. -

-

--- @@ -142,9 +128,7 @@ sections: icon: hl-whooglesearch ``` -

-

--- @@ -166,9 +150,7 @@ sections: icon: mdi-google-downasaur ``` -

-

--- diff --git a/docs/license.md b/docs/license.md index 114d145a..6af4c293 100644 --- a/docs/license.md +++ b/docs/license.md @@ -1,27 +1,27 @@ -# License - -## MIT License - -Copyright (c) 2021 Alicia Sykes - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. - ---- - -For more information about the MIT License, see: https://opensource.org/licenses/MIT \ No newline at end of file +# License + +## MIT License + +Copyright (c) 2021 Alicia Sykes + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +--- + +For more information about the MIT License, see: https://opensource.org/licenses/MIT diff --git a/docs/management.md b/docs/management.md index 446ceb5d..c24e4d88 100644 --- a/docs/management.md +++ b/docs/management.md @@ -47,7 +47,7 @@ In Dashy, commonly configured resources include: If you're running an app in Docker, then commands will need to be passed to the container to be executed. This can be done by preceding each command with `docker exec -it [container-id]`, where container ID can be found by running `docker ps`. For example `docker exec -it 26c156c467b4 yarn build`. You can also enter the container, with `docker exec -it [container-id] /bin/ash`, and navigate around it with normal Linux commands. -Dashy has several commands that can be used for various tasks, you can find a list of these either in the [Developing Docs](/developing.md#project-commands), or by looking at the [`package.json`](https://github.com/Lissy93/dashy/blob/master/package.json#L5). These can be used by running `yarn [command-name]`. +Dashy has several commands that can be used for various tasks, you can find a list of these either in the [Developing Docs](/docs/developing.md#project-commands), or by looking at the [`package.json`](https://github.com/Lissy93/dashy/blob/master/package.json#L5). These can be used by running `yarn [command-name]`. ****[โฌ†๏ธ Back to Top](#)**** @@ -201,7 +201,7 @@ All configuration and dashboard settings are stored in your `user-data/conf.yml` Since Dashy is open source, there shouldn't be any need to backup the main container. -Dashy also has a built-in cloud backup feature, which is free for personal users, and will let you make and restore fully encrypted backups of your config directly through the UI. To learn more, see the [Cloud Backup Docs](/backup-restore) +Dashy also has a built-in cloud backup feature, which is free for personal users, and will let you make and restore fully encrypted backups of your config directly through the UI. To learn more, see the [Cloud Backup Docs](/docs/backup-restore) ****[โฌ†๏ธ Back to Top](#)**** @@ -256,7 +256,7 @@ Once everything is setup, you can verify your site is secured using a tool like ## Authentication -Dashy natively supports secure authentication using KeyCloak. There is also a Simple Auth feature that doesn't require any additional setup. Usage instructions for both, as well as alternative auth methods, has now moved to the **[Authentication Docs](/authentication)** page. +Dashy natively supports secure authentication using KeyCloak. There is also a Simple Auth feature that doesn't require any additional setup. Usage instructions for both, as well as alternative auth methods, has now moved to the **[Authentication Docs](/docs/authentication)** page. ****[โฌ†๏ธ Back to Top](#)**** @@ -298,7 +298,7 @@ services: ## Passing in Environmental Variables -With Docker, you can define environmental variables under the `environment` section of your Docker compose file. Environmental variables are used to configure high-level settings, usually before the config file has been read. For a list of all supported env vars in Dashy, see [the developing docs](/developing.md#environmental-variables), or the default [`.env`](https://github.com/Lissy93/dashy/blob/master/.env) file. +With Docker, you can define environmental variables under the `environment` section of your Docker compose file. Environmental variables are used to configure high-level settings, usually before the config file has been read. For a list of all supported env vars in Dashy, see [the developing docs](/docs/developing.md#environmental-variables), or the default [`.env`](https://github.com/Lissy93/dashy/blob/master/.env) file. A common use case, is to run Dashy under a sub-page, instead of at the root of a URL (e.g. `https://my-homelab.local/dashy` instead of `https://dashy.my-homelab.local`). In this use-case, you'd specify the `BASE_URL` variable in your compose file. @@ -432,25 +432,25 @@ Using a VPN is one of the easiest ways to provide secure, full access to your lo #### **Example Server Config** ```ini -## Server file +# Server file [Interface] -## Which networks does my interface belong to? Notice: /24 and /64 +# Which networks does my interface belong to? Notice: /24 and /64 Address = 10.5.0.1/24, 2001:470:xxxx:xxxx::1/64 PrivateKey = xxx ListenPort = 51820 -## Peer 1 +# Peer 1 [Peer] PublicKey = xxx -## Which source IPs can I expect from that peer? Notice: /32 and /128 +# Which source IPs can I expect from that peer? Notice: /32 and /128 AllowedIps = 10.5.0.35/32, 2001:470:xxxx:xxxx::746f:786f/128 -## Peer 2 +# Peer 2 [Peer] PublicKey = xxx -## Which source IPs can I expect from that peer? This one has a LAN which can -## access hosts/jails without NAT. -## Peer 2 has a single IP address inside the VPN: it's 10.5.0.25/32 +# Which source IPs can I expect from that peer? This one has a LAN which can +# access hosts/jails without NAT. +# Peer 2 has a single IP address inside the VPN: it's 10.5.0.25/32 AllowedIps = 10.5.0.25/32,10.21.10.0/24,10.21.20.0/24,10.21.30.0/24,10.31.0.0/24,2001:470:xxxx:xxxx::ca:571e/128 ``` @@ -458,21 +458,21 @@ AllowedIps = 10.5.0.25/32,10.21.10.0/24,10.21.20.0/24,10.21.30.0/24,10.31.0.0/24 ```ini [Interface] -## Which networks does my interface belong to? Notice: /24 and /64 +# Which networks does my interface belong to? Notice: /24 and /64 Address = 10.5.0.35/24, 2001:470:xxxx:xxxx::746f:786f/64 PrivateKey = xxx -## Server +# Server [Peer] PublicKey = xxx -## I want to route everything through the server, both IPv4 and IPv6. All IPs are -## thus available through the Server, and I can expect packets from any IP to -## come from that peer. +# I want to route everything through the server, both IPv4 and IPv6. All IPs are +# thus available through the Server, and I can expect packets from any IP to +# come from that peer. AllowedIPs = 0.0.0.0/0, ::0/0 -## Where is the server on the internet? This is a public address. The port -## (:51820) is the same as ListenPort in the [Interface] of the Server file above +# Where is the server on the internet? This is a public address. The port +# (:51820) is the same as ListenPort in the [Interface] of the Server file above Endpoint = 1.2.3.4:51820 -## Usually, clients are behind NAT. to keep the connection running, keep alive. +# Usually, clients are behind NAT. to keep the connection running, keep alive. PersistentKeepalive = 15 ``` @@ -515,7 +515,7 @@ To get started, [Download](https://ngrok.com/download) and install Ngrok for you Some Ngrok features require you to be authenticated, you can [create a free account](https://dashboard.ngrok.com/signup) and generate a token in [your dashboard](https://dashboard.ngrok.com/auth/your-authtoken), then run `ngrok authtoken [token]`. -It's recommended to use authentication for any publicly accessible service. Dashy has an [Auth](/authentication) feature built in, but an even easier method it to use the [`-auth`](https://ngrok.com/docs#http-auth) switch. E.g. `ngrok http -auth="username:password123" 8080` +It's recommended to use authentication for any publicly accessible service. Dashy has an [Auth](/docs/authentication) feature built in, but an even easier method it to use the [`-auth`](https://ngrok.com/docs#http-auth) switch. E.g. `ngrok http -auth="username:password123" 8080` By default, your web app is assigned a randomly generated ngrok domain, but you can also use your own custom domain. Under the [Domains Tab](https://dashboard.ngrok.com/endpoints/domains) of your Ngrok dashboard, add your domain, and follow the CNAME instructions. You can now use your domain, with the [`-hostname`](https://ngrok.com/docs#http-custom-domains) switch, e.g. `ngrok http -region=us -hostname=dashy.example.com 8080`. If you don't have your own domain name, you can instead use a custom sub-domain (e.g. `alicia-dashy.ngrok.io`), using the [`-subdomain`](https://ngrok.com/docs#custom-subdomain-names) switch. @@ -888,7 +888,7 @@ Create a file names `firebase.json`, and populate it with something similar to: If you'd like to make any code changes to the app, and deploy your modified version, this section briefly explains how. -The first step is to fork the project on GitHub, and clone it to your local system. Next, install the dependencies (`yarn`), and start the development server (`yarn dev`) and visit `localhost:8080` in your browser. You can then make changes to the codebase, and see the live app update in real-time. Once you've finished, running `yarn build` will build the app for production, and output the assets into `./dist` which can then be deployed using a web server, CDN or the built-in Node server with `yarn start`. For more info on all of this, take a look at the [Developing Docs](/developing). To build your own Docker container from the modified app, see [Building your Own Container](#building-your-own-container) +The first step is to fork the project on GitHub, and clone it to your local system. Next, install the dependencies (`yarn`), and start the development server (`yarn dev`) and visit `localhost:8080` in your browser. You can then make changes to the codebase, and see the live app update in real-time. Once you've finished, running `yarn build` will build the app for production, and output the assets into `./dist` which can then be deployed using a web server, CDN or the built-in Node server with `yarn start`. For more info on all of this, take a look at the [Developing Docs](/docs/developing). To build your own Docker container from the modified app, see [Building your Own Container](#building-your-own-container) ****[โฌ†๏ธ Back to Top](#)**** diff --git a/docs/pages-and-sections.md b/docs/pages-and-sections.md index 38f4b2e2..dad42f89 100644 --- a/docs/pages-and-sections.md +++ b/docs/pages-and-sections.md @@ -1,107 +1,105 @@ -# Pages and Sections - -## Multi-Page Support - -You can have additional pages within your dashboard, with each having it's own config file. The config files for sub-pages can either be stored locally, or hosted separately. A link to each additional page will be displayed in the navigation bar. - -You can edit additional pages using the interactive editor, exactly the same was as your primary page (so long as it's local). But please save changes to one page, before you start editing the next. - -### Using Local Sub-Pages - -To get started, create a new `.yml` config file for your sub-page, placing it within `/app/user-data`. Then within your primary `conf.yml`, choose a name, and specify the path to the new file. - -This is an example. Make sure to add this to the topmost line above appConfig:, or anywhere else appropriately, to match the yml syntax. - -```yaml -pages: -- name: Networking Services - path: 'networking.yml' -- name: Work Stuff - path: 'work.yml' -``` - -The next step is to create the new page, if you mounted `/app/user-data` in the docker command and not a volume, you can simply create the new page into that folder on the host. - -If you mounted `/app/user-data/conf.yml` in docker, you can either switch to the volume or create another bind mount to your new additional page. - -If you're sub-page is located within `/app/user-data`, then you only need to specify the filename, but if it's anywhere else, then the full path is required. - -A default template a page can be found here: [https://github.com/lissy93/dashy/blob/master/user-data/conf.yml](https://github.com/lissy93/dashy/blob/master/user-data/conf.yml) Keep in mind the appConfig cannot be used on subpages and should be removed, for further info see [Restrictions](#restrictions) - -The last very important step is to rebuild dashy, this can be easily done through to UI, by opening the settings menu on the top right, navigato to update config and then recompile application. - -Now if you reload the page, on the top right there should be a new button to navigate to the new page. ๐ŸŽ‰ - -### Using Remote Sub-Pages - -Config files don't need to be local, you can store them anywhere, and data will be imported as sub-pages on page load. - -For example: - -```yaml -pages: -- name: Getting Started - path: 'https://snippet.host/tvcw/raw' -- name: Homelab - path: 'https://snippet.host/tetp/raw' -- name: Browser Startpage - path: 'https://snippet.host/zcom/raw' -``` - -There are many options of how this can be used. You could store your config within a Git repository, in order to easily track and rollback changes. Or host your config on your NAS, to have it backed up with the rest of your files. Or use a hosted paste service, for example [snippet.host](https://snippet.host/), which supports never-expiring CORS-enabled pastes, which can also be edited later. - -You will obviously not be able to write updates to remote configs directly through the UI editor, but you can still make and preview changes, then use the export menu to get a copy of the new config, which can then be pasted to the remote source manually. -The config file must, of course be accessible from within Dashy. If your config contains sensitive info (like API keys, credentials, secret URLs, etc), take care not to expose it to the internet. - -The following example shows creating a config, publishing it as a [Gist](https://gist.github.com/), copying the URL to the raw file, and using it within your dashboard. - -

- Public config in a gist demo -

- -### Restrictions - -Only top-level fields supported by sub-pages are `pageInfo` and `sections`. The `appConfig` and `pages` will always be inherited from your main `conf.yml` file. Other than that, sub-pages behave exactly the same as your default view, and can contain sections, items, widgets and page info like nav links, title and logo. - -Note that since page paths are required by the router, they are set at build-time, not run-time, and so a rebuild (happens automatically) is required for changes to page paths to take effect (this only applies to changes to the `pages` array, rebuild isn't required for editing page content). - -## Sub-Items - -A normal section will contain zero or more items, for example: - -```yaml -- name: Coding - icon: far fa-code - items: - - title: GitHub - url: https://github.com/ - - title: StackOverflow - url: http://stackoverflow.com/ -``` - -But items can also be grouped together, referred to as sub-items. This is useful for a group of less frequently used items, which you don't want to take up too much space. - -Item groups may also have an optional title. - -```yaml -- name: Coding - icon: far fa-code - items: - - title: Normal Item 1 - - title: Normal Item 2 - - subItems: - - title: JavaScript - url: https://developer.mozilla.org - icon: si-javascript - - title: TypeScript - url: https://www.typescriptlang.org/docs - icon: si-typescript - - title: Svelt - url: https://svelte.dev/docs - icon: si-svelte - - title: Go - url: https://go.dev/doc - icon: si-go -``` +# Pages and Sections + +## Multi-Page Support + +You can have additional pages within your dashboard, with each having it's own config file. The config files for sub-pages can either be stored locally, or hosted separately. A link to each additional page will be displayed in the navigation bar. + +You can edit additional pages using the interactive editor, exactly the same was as your primary page (so long as it's local). But please save changes to one page, before you start editing the next. + +### Using Local Sub-Pages + +To get started, create a new `.yml` config file for your sub-page, placing it within `/app/user-data`. Then within your primary `conf.yml`, choose a name, and specify the path to the new file. + +This is an example. Make sure to add this to the topmost line above appConfig:, or anywhere else appropriately, to match the yml syntax. + +```yaml +pages: +- name: Networking Services + path: 'networking.yml' +- name: Work Stuff + path: 'work.yml' +``` + +The next step is to create the new page, if you mounted `/app/user-data` in the docker command and not a volume, you can simply create the new page into that folder on the host. + +If you mounted `/app/user-data/conf.yml` in docker, you can either switch to the volume or create another bind mount to your new additional page. + +If you're sub-page is located within `/app/user-data`, then you only need to specify the filename, but if it's anywhere else, then the full path is required. + +A default template a page can be found here: [https://github.com/lissy93/dashy/blob/master/user-data/conf.yml](https://github.com/lissy93/dashy/blob/master/user-data/conf.yml) Keep in mind the appConfig cannot be used on subpages and should be removed, for further info see [Restrictions](#restrictions) + +The last very important step is to rebuild dashy, this can be easily done through to UI, by opening the settings menu on the top right, navigato to update config and then recompile application. + +Now if you reload the page, on the top right there should be a new button to navigate to the new page. ๐ŸŽ‰ + +### Using Remote Sub-Pages + +Config files don't need to be local, you can store them anywhere, and data will be imported as sub-pages on page load. + +For example: + +```yaml +pages: +- name: Getting Started + path: 'https://snippet.host/tvcw/raw' +- name: Homelab + path: 'https://snippet.host/tetp/raw' +- name: Browser Startpage + path: 'https://snippet.host/zcom/raw' +``` + +There are many options of how this can be used. You could store your config within a Git repository, in order to easily track and rollback changes. Or host your config on your NAS, to have it backed up with the rest of your files. Or use a hosted paste service, for example [snippet.host](https://snippet.host/), which supports never-expiring CORS-enabled pastes, which can also be edited later. + +You will obviously not be able to write updates to remote configs directly through the UI editor, but you can still make and preview changes, then use the export menu to get a copy of the new config, which can then be pasted to the remote source manually. +The config file must, of course be accessible from within Dashy. If your config contains sensitive info (like API keys, credentials, secret URLs, etc), take care not to expose it to the internet. + +The following example shows creating a config, publishing it as a [Gist](https://gist.github.com/), copying the URL to the raw file, and using it within your dashboard. + + Public config in a gist demo + +### Restrictions + +Only top-level fields supported by sub-pages are `pageInfo` and `sections`. The `appConfig` and `pages` will always be inherited from your main `conf.yml` file. Other than that, sub-pages behave exactly the same as your default view, and can contain sections, items, widgets and page info like nav links, title and logo. + +Note that since page paths are required by the router, they are set at build-time, not run-time, and so a rebuild (happens automatically) is required for changes to page paths to take effect (this only applies to changes to the `pages` array, rebuild isn't required for editing page content). + +## Sub-Items + +A normal section will contain zero or more items, for example: + +```yaml +- name: Coding + icon: far fa-code + items: + - title: GitHub + url: https://github.com/ + - title: StackOverflow + url: http://stackoverflow.com/ +``` + +But items can also be grouped together, referred to as sub-items. This is useful for a group of less frequently used items, which you don't want to take up too much space. + +Item groups may also have an optional title. + +```yaml +- name: Coding + icon: far fa-code + items: + - title: Normal Item 1 + - title: Normal Item 2 + - subItems: + - title: JavaScript + url: https://developer.mozilla.org + icon: si-javascript + - title: TypeScript + url: https://www.typescriptlang.org/docs + icon: si-typescript + - title: Svelt + url: https://svelte.dev/docs + icon: si-svelte + - title: Go + url: https://go.dev/doc + icon: si-go +``` diff --git a/docs/privacy.md b/docs/privacy.md index 06a30a9f..4b0c3570 100644 --- a/docs/privacy.md +++ b/docs/privacy.md @@ -88,7 +88,7 @@ Your selected password never leaves your device, and is hashed before being comp #### Web Search -Dashy has a primitive [web search feature](/docs/searching#web-search). No external requests are made, instead you are redirected to your chosen search engine (defaults to DuckDuckGo), using your chosen opening method. +Dashy has a primitive [web search feature](/docs/searching.md#web-search). No external requests are made, instead you are redirected to your chosen search engine (defaults to DuckDuckGo), using your chosen opening method. This feature can be disabled under appConfig, with `webSearch: { disableWebSearch: true }` @@ -112,57 +112,57 @@ Certain themes may use external assets (such as fonts or images). Currently, thi ### Widgets -Dashy supports [Widgets](/widgets) for displaying dynamic content. Below is a list of all widgets that make external data requests, along with the endpoint they call and a link to the Privacy Policy of that service. +Dashy supports [Widgets](/docs/widgets) for displaying dynamic content. Below is a list of all widgets that make external data requests, along with the endpoint they call and a link to the Privacy Policy of that service. -- **[Weather](/widgets.md#weather)** and **[Weather Forecast](/widgets.md#weather-forecast)**: `https://api.openweathermap.org` +- **[Weather](/docs/widgets.md#weather)** and **[Weather Forecast](/docs/widgets.md#weather-forecast)**: `https://api.openweathermap.org` - [OWM Privacy Policy](https://openweather.co.uk/privacy-policy) -- **[RSS Feed](/widgets.md#rss-feed)**: `https://api.rss2json.com/v1/api.json` +- **[RSS Feed](/docs/widgets.md#rss-feed)**: `https://api.rss2json.com/v1/api.json` - [Rss2Json Privacy Policy](https://rss2json.com/privacy-policy) -- **[IP Address](/widgets.md#public-ip)**: `https://ipapi.co/json` or `http://ip-api.com/json` or `https://api.ip2location.io/` +- **[IP Address](/docs/widgets.md#public-ip)**: `https://ipapi.co/json` or `http://ip-api.com/json` or `https://api.ip2location.io/` - [IPGeoLocation Privacy Policy](https://ipgeolocation.io/privacy.html) - [IP-API Privacy Policy](https://ip-api.com/docs/legal) - [IP2Location.io Privacy Policy](https://ip2location.io/privacy-policy) -- **[IP Blacklist](/widgets.md#ip-blacklist)**: `https://api.blacklistchecker.com` +- **[IP Blacklist](/docs/widgets.md#ip-blacklist)**: `https://api.blacklistchecker.com` - [Blacklist Checker Privacy Policy](https://blacklistchecker.com/privacy) -- **[Domain Monitor](/widgets.md#domain-monitor)**: `http://api.whoapi.com` +- **[Domain Monitor](/docs/widgets.md#domain-monitor)**: `http://api.whoapi.com` - [WhoAPI Privacy Policy](https://whoapi.com/privacy-policy/) -- **[Crypto Watch List](/widgets.md#crypto-watch-list)** and **[Token Price History](/widgets.md#crypto-token-price-history)**: `https://api.coingecko.com` +- **[Crypto Watch List](/docs/widgets.md#crypto-watch-list)** and **[Token Price History](/docs/widgets.md#crypto-token-price-history)**: `https://api.coingecko.com` - [CoinGecko Privacy Policy](https://www.coingecko.com/en/privacy) -- **[Wallet Balance](/widgets.md#wallet-balance)**: `https://api.blockcypher.com/` +- **[Wallet Balance](/docs/widgets.md#wallet-balance)**: `https://api.blockcypher.com/` - [BlockCypher Privacy Policy](https://www.blockcypher.com/privacy.html) -- **[Code::Stats](/widgets.md#code-stats)**: `https://codestats.net` +- **[Code::Stats](/docs/widgets.md#code-stats)**: `https://codestats.net` - [Code::Stats Privacy Policy](https://codestats.net/tos#privacy) -- **[addy.io](/widgets.md#addyio)**: `https://app.addy.io` +- **[addy.io](/docs/widgets.md#addyio)**: `https://app.addy.io` - [addy.io Privacy Policy](https://addy.io/privacy/) -- **[Vulnerability Feed](/widgets.md#vulnerability-feed)**: `https://www.cvedetails.com` +- **[Vulnerability Feed](/docs/widgets.md#vulnerability-feed)**: `https://www.cvedetails.com` - [CVE Details Privacy Policy](https://www.cvedetails.com/privacy.php) -- **[Exchange Rate](/widgets.md#exchange-rates)**: `https://v6.exchangerate-api.com` +- **[Exchange Rate](/docs/widgets.md#exchange-rates)**: `https://v6.exchangerate-api.com` - [ExchangeRateAPI Privacy Policy](https://www.exchangerate-api.com/terms) -- **[Public Holidays](/widgets.md#public-holidays)**: `https://kayaposoft.com` +- **[Public Holidays](/docs/widgets.md#public-holidays)**: `https://kayaposoft.com` - [jurajmajer/enrico](https://github.com/jurajmajer/enrico) -- **[Covid-19 Status](/widgets.md#covid-19-status)**: `https://codestats.net` +- **[Covid-19 Status](/docs/widgets.md#covid-19-status)**: `https://codestats.net` - [disease-sh/api](https://github.com/disease-sh/api) -- **[Sports Scores](/widgets.md#sports-scores)**: `https://thesportsdb.com` +- **[Sports Scores](/docs/widgets.md#sports-scores)**: `https://thesportsdb.com` - No Policy Available -- **[News Headlines](/widgets.md#news-headlines)**: `https://api.currentsapi.services` +- **[News Headlines](/docs/widgets.md#news-headlines)**: `https://api.currentsapi.services` - [CurrentsAPI Privacy Policy](https://currentsapi.services/privacy) -- **[Mullvad Status](/widgets.md#mullvad-status)**: `https://am.i.mullvad.net` +- **[Mullvad Status](/docs/widgets.md#mullvad-status)**: `https://am.i.mullvad.net` - [Mullvad Privacy Policy](https://mullvad.net/en/help/privacy-policy/) -- **[TFL Status](/widgets.md#tfl-status)**: `https://api.tfl.gov.uk` +- **[TFL Status](/docs/widgets.md#tfl-status)**: `https://api.tfl.gov.uk` - [TFL Privacy Policy](https://tfl.gov.uk/corporate/privacy-and-cookies/) -- **[Stock Price History](/widgets.md#stock-price-history)**: `https://alphavantage.co` +- **[Stock Price History](/docs/widgets.md#stock-price-history)**: `https://alphavantage.co` - [AlphaVantage Privacy Policy](https://www.alphavantage.co/privacy/) -- **[ETH Gas Prices](/widgets.md#eth-gas-prices)**: `https://ethgas.watch` +- **[ETH Gas Prices](/docs/widgets.md#eth-gas-prices)**: `https://ethgas.watch` - [wslyvh/ethgaswatch](https://github.com/wslyvh/ethgaswatch) -- **[Joke](/widgets.md#joke)**: `https://v2.jokeapi.dev` +- **[Joke](/docs/widgets.md#joke)**: `https://v2.jokeapi.dev` - [SV443's Privacy Policy](https://sv443.net/privacypolicy/en) -- **[Flight Data](/widgets.md#flight-data)**: `https://aerodatabox.p.rapidapi.com` +- **[Flight Data](/docs/widgets.md#flight-data)**: `https://aerodatabox.p.rapidapi.com` - [AeroDataBox Privacy Policy](https://www.aerodatabox.com/#h.p_CXtIYZWF_WQd) -- **[Astronomy Picture of the Day](/widgets.md#astronomy-picture-of-the-day)**: `https://apodapi.herokuapp.com` +- **[Astronomy Picture of the Day](/docs/widgets.md#astronomy-picture-of-the-day)**: `https://apodapi.herokuapp.com` - [NASA's Privacy Policy](https://www.nasa.gov/about/highlights/HP_Privacy.html) -- **[GitHub Trending](/widgets.md#github-trending)** and **[GitHub Profile Stats](/widgets.md#github-profile-stats)**: `https://api.github.com` +- **[GitHub Trending](/docs/widgets.md#github-trending)** and **[GitHub Profile Stats](/docs/widgets.md#github-profile-stats)**: `https://api.github.com` - [GitHub's Privacy Policy](https://docs.github.com/en/github/site-policy/github-privacy-statement) -- **[Cron Monitoring (Health Checks)](/widgets.md#cron-monitoring-health-checks)**: `https://healthchecks.io` +- **[Cron Monitoring (Health Checks)](/docs/widgets.md#cron-monitoring-health-checks)**: `https://healthchecks.io` - [Health-Checks Privacy Policy](https://healthchecks.io/privacy/) --- @@ -211,13 +211,13 @@ The following section outlines all data that is stored in the browsers, as cooki ### Deleting Stored Data -You can manually view and delete session storage, local storage and cookies at anytime. Fist [open](/troubleshooting.md#how-to-open-browser-console) your browsers developer tools (usually F12), then under the Application tab select the storage category. Here you will see a list of stored data, and you can select any item and delete it. +You can manually view and delete session storage, local storage and cookies at anytime. Fist [open](/docs/troubleshooting.md#how-to-open-browser-console) your browsers developer tools (usually F12), then under the Application tab select the storage category. Here you will see a list of stored data, and you can select any item and delete it. --- ## Dependencies -As with most web projects, Dashy relies on several [dependencies](/docs/credits#dependencies-). For links to each, and a breakdown of their licenses, please see [Legal](https://github.com/Lissy93/dashy/blob/master/.github/LEGAL). +As with most web projects, Dashy relies on several [dependencies](/docs/credits.md#dependencies-). For links to each, and a breakdown of their licenses, please see [Legal](https://github.com/Lissy93/dashy/blob/master/.github/LEGAL). Dependencies can introduce security vulnerabilities, but since all these packages are open source any issues are usually very quickly spotted. Dashy is using Snyk for dependency security monitoring, and you can see [the latest report here](https://snyk.io/test/github/lissy93/dashy). If any issue is detected by Snyk, a note about it will appear at the top of the Readme, and will usually be fixed within 48 hours. @@ -229,12 +229,12 @@ Note that packages listed under `devDependencies` section are only used for buil Running your self-hosted applications in individual, containerized environments (such as containers or VMs) helps keep them isolated, and prevent an exploit in one service effecting another. -If you're running Dashy in a container, see [Management Docs --> Container Security](/docs/management#container-security) for step-by-step security guide. +If you're running Dashy in a container, see [Management Docs --> Container Security](/docs/management.md#container-security) for step-by-step security guide. There is very little complexity involved with Dashy, and therefore the attack surface is reasonably small, but it is still important to follow best practices and employ monitoring for all your self-hosted apps. A couple of things that you should look at include: - Use SSL for securing traffic in transit -- Configure [authentication](/authentication.md#alternative-authentication-methods) to prevent unauthorized access +- Configure [authentication](/docs/authentication.md#alternative-authentication-methods) to prevent unauthorized access - Keep your system, software and Dashy up-to-date - Ensure your server is appropriately secured - Manage users and SSH correctly @@ -243,7 +243,7 @@ There is very little complexity involved with Dashy, and therefore the attack su - Setup malicious traffic detection - Understand the [Docker attack fronts](https://docs.docker.com/engine/security/), and follow [Docker Security Best Practices](https://snyk.io/blog/10-docker-image-security-best-practices/) -This is covered in more detail in [App Management](/management). +This is covered in more detail in [App Management](/docs/management). --- @@ -257,11 +257,11 @@ Dashy supports SRI, and it is recommended to enable this if you are hosting your ### SSL -Native SSL support is enabled, for setup instructions, see the [Management Docs](/management.md#ssl-certificates) +Native SSL support is enabled, for setup instructions, see the [Management Docs](/docs/management.md#ssl-certificates) ### Authentication -Dashy supports both basic auth, as well as server-based SSO using Keycloak. Full details of which, along with alternate authentication methods can be found in the [Authentication Docs](/authentication). If your dashboard is exposed to the internet and/ or contains any sensitive info it is strongly recommended to configure access control with Keycloak or another server-side method. +Dashy supports both basic auth, as well as server-based SSO using Keycloak. Full details of which, along with alternate authentication methods can be found in the [Authentication Docs](/docs/authentication). If your dashboard is exposed to the internet and/ or contains any sensitive info it is strongly recommended to configure access control with Keycloak or another server-side method. --- diff --git a/docs/quick-start.md b/docs/quick-start.md index 2de2ab5c..65770847 100644 --- a/docs/quick-start.md +++ b/docs/quick-start.md @@ -26,7 +26,7 @@ docker run -d \ lissy93/dashy:latest ``` -Either replace the -v path to point to your config file, or leave it out. For a full list of available options, then see [Dashy with Docker](/docs/deployment#deploy-with-docker) Docs. If you'd prefer to use Docker Compose, then see [Dashy with Docker Compose](/docs/deployment#using-docker-compose) Docs. Alternate registries, architectures and pinned versions are also supported. +Either replace the -v path to point to your config file, or leave it out. For a full list of available options, then see [Dashy with Docker](/docs/deployment.md#deploy-with-docker) Docs. If you'd prefer to use Docker Compose, then see [Dashy with Docker Compose](/docs/deployment.md#using-docker-compose) Docs. Alternate registries, architectures and pinned versions are also supported. Your dashboard should now be up and running at `http://localhost:8080` (or your servers IP address/ domain, and the port that you chose). The first time you build, it may take a few minutes. @@ -43,7 +43,7 @@ For example, if you had `user-data/favicon.ico` this would be accessible at `htt Example Files in `user-data`: - `conf.yml` - This is the only file that is compulsory, it's your main Dashy config -- `**.yml` - Include more config files, if you'd like to have multiple pages, see [Multi-page support](/pages-and-sections.md#multi-page-support) for docs +- `**.yml` - Include more config files, if you'd like to have multiple pages, see [Multi-page support](/docs/pages-and-sections.md#multi-page-support) for docs - `favicon.ico` - The default favicon, shown in the browser's tab title - `initialization.html` - Static HTML page displayed before the app has finished compiling, see [`public/initialization.html`](https://github.com/Lissy93/dashy/blob/master/public/initialization.html) - `robots.txt` - Search engine crawl rules, override this if you want your dashboard to be indexable @@ -51,7 +51,7 @@ Example Files in `user-data`: - `index.html` - The main index page which initializes the client-side app, copy it from [`/public/index.html`](https://github.com/Lissy93/dashy/blob/master/public/index.html) - `**.html` - Write your own HTML pages, and access them at `http://my-dashy-instance.local/my-page.html` - `fonts/` - Custom fonts (be sure to include the ones already in [`public/fonts`](https://github.com/Lissy93/dashy/tree/master/public/fonts) -- `item-icons/` - To use your own icons for items on your dashboard, see [Icons --> Local Icons](/icons.md#local-icons) +- `item-icons/` - To use your own icons for items on your dashboard, see [Icons --> Local Icons](/docs/icons.md#local-icons) - `web-icons/` - Override Dashy logo - `widget-resources/` - Fonts, icons and assets for custom widgets @@ -63,10 +63,10 @@ Now that you've got Dashy running, you are going to want to set it up with your Config is written in [YAML Format](https://yaml.org/), and saved in [`/user-data/conf.yml`](https://github.com/Lissy93/dashy/blob/master/user-data/conf.yml). The format on the config file is pretty straight forward. There are four root attributes: -- [`pageInfo`](/docs/configuring#pageinfo) - Dashboard meta data, like title, description, nav bar links and footer text -- [`appConfig`](/docs/configuring#appconfig-optional) - Dashboard settings, like themes, authentication, language and customization -- [`sections`](/docs/configuring#section) - An array of sections, each including an array of items -- [`pages`](/docs/configuring#pages-optional) - Have multiples pages in your dashboard +- [`pageInfo`](/docs/configuring.md#pageinfo) - Dashboard meta data, like title, description, nav bar links and footer text +- [`appConfig`](/docs/configuring.md#appconfig-optional) - Dashboard settings, like themes, authentication, language and customization +- [`sections`](/docs/configuring.md#section) - An array of sections, each including an array of items +- [`pages`](/docs/configuring.md#pages-optional) - Have multiples pages in your dashboard You can view a full list of all available config options in the [Configuring Docs](/docs/configuring). @@ -112,14 +112,14 @@ Once you've got Dashy setup, you'll want to ensure the container is properly hea You might also want to check out the docs for specific features you'd like to use: -- [Authentication](/authentication) - Setting up authentication to protect your dashboard -- [Alternate Views](/alternate-views) - Using the startpage and workspace view -- [Backup & Restore](/backup-restore) - Guide to Dashy's cloud sync feature -- [Icons](/icons) - Outline of all available icon types for sections and items -- [Localisation](/multi-language-support) - How to change language, or add your own -- [Status Indicators](/status-indicators) - Using Dashy to monitor uptime and status of your apps -- [Search & Shortcuts](/searching) - Using instant filter, web search and custom hotkeys -- [Theming](/theming) - Complete guide to applying, writing and modifying themes and styles +- [Authentication](/docs/authentication) - Setting up authentication to protect your dashboard +- [Alternate Views](/docs/alternate-views) - Using the startpage and workspace view +- [Backup & Restore](/docs/backup-restore) - Guide to Dashy's cloud sync feature +- [Icons](/docs/icons) - Outline of all available icon types for sections and items +- [Localisation](/docs/multi-language-support) - How to change language, or add your own +- [Status Indicators](/docs/status-indicators) - Using Dashy to monitor uptime and status of your apps +- [Search & Shortcuts](/docs/searching) - Using instant filter, web search and custom hotkeys +- [Theming](/docs/theming) - Complete guide to applying, writing and modifying themes and styles --- @@ -150,7 +150,7 @@ Then edit `./user-data/conf.yml` ## Alternative Deployment Method 2 - Netlify -Don't have a server? No problem! You can run Dashy for free on Netlify (as well as many [other cloud providers](/deployment.md#deploy-to-cloud-service)). All you need it a GitHub account. +Don't have a server? No problem! You can run Dashy for free on Netlify (as well as many [other cloud providers](/docs/deployment.md#deploy-to-cloud-service)). All you need it a GitHub account. 1. Fork Dashy's repository on GitHub 2. [Log in](app.netlify.com/login/) to Netlify with GitHub diff --git a/docs/readme.md b/docs/readme.md index ec5072af..8e63eae4 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -2,37 +2,37 @@ ## Running Dashy -- [Quick Start](/quick-start) - TLDR guide on getting Dashy up and running -- [Deployment](/deployment) - Full guide on deploying Dashy either locally or online -- [Configuring](/configuring) - Complete list of all available options in the config file -- [App Management](/management) - Managing your app, updating, security, web server configuration, etc -- [Troubleshooting](/troubleshooting) - Common errors and problems, and how to fix them +- [Quick Start](/docs/quick-start) - TLDR guide on getting Dashy up and running +- [Deployment](/docs/deployment) - Full guide on deploying Dashy either locally or online +- [Configuring](/docs/configuring) - Complete list of all available options in the config file +- [App Management](/docs/management) - Managing your app, updating, security, web server configuration, etc +- [Troubleshooting](/docs/troubleshooting) - Common errors and problems, and how to fix them ## Development and Contributing -- [Developing](/developing) - Running Dashy development server locally, and general workflow -- [Development Guides](/development-guides) - Common development tasks, to help new contributors -- [Contributing](/contributing) - How you can help keep Dashy alive -- [Showcase](/showcase) - See how others are using Dashy, and share your dashboard -- [Credits](/credits) - List of people and projects that have made Dashy possible -- [Release Workflow](/release-workflow) - Info about releases, CI and automated tasks +- [Developing](/docs/developing) - Running Dashy development server locally, and general workflow +- [Development Guides](/docs/development-guides) - Common development tasks, to help new contributors +- [Contributing](/docs/contributing) - How you can help keep Dashy alive +- [Showcase](/docs/showcase) - See how others are using Dashy, and share your dashboard +- [Credits](/docs/credits) - List of people and projects that have made Dashy possible +- [Release Workflow](/docs/release-workflow) - Info about releases, CI and automated tasks ## Feature Docs -- [Authentication](/authentication) - Guide to setting up authentication to protect your dashboard -- [Alternate Views](/alternate-views) - Outline of available pages / views and item opening methods -- [Backup & Restore](/backup-restore) - Guide to backing up config with Dashy's cloud sync feature -- [Icons](/icons) - Outline of all available icon types for sections and items, with examples -- [Language Switching](/multi-language-support) - Details on how to switch language, or add a new locale -- [Pages and Sections](/pages-and-sections) - Multi-page support, sections, items and sub-items -- [Status Indicators](/status-indicators) - Using Dashy to monitor uptime and status of your apps -- [Searching & Shortcuts](/searching) - Searching, launching methods + keyboard shortcuts -- [Theming](/theming) - Complete guide to applying, writing and modifying themes + styles -- [Widgets](/widgets) - List of all dynamic content widgets, with usage guides and examples +- [Authentication](/docs/authentication) - Guide to setting up authentication to protect your dashboard +- [Alternate Views](/docs/alternate-views) - Outline of available pages / views and item opening methods +- [Backup & Restore](/docs/backup-restore) - Guide to backing up config with Dashy's cloud sync feature +- [Icons](/docs/icons) - Outline of all available icon types for sections and items, with examples +- [Language Switching](/docs/multi-language-support) - Details on how to switch language, or add a new locale +- [Pages and Sections](/docs/pages-and-sections) - Multi-page support, sections, items and sub-items +- [Status Indicators](/docs/status-indicators) - Using Dashy to monitor uptime and status of your apps +- [Searching & Shortcuts](/docs/searching) - Searching, launching methods + keyboard shortcuts +- [Theming](/docs/theming) - Complete guide to applying, writing and modifying themes + styles +- [Widgets](/docs/widgets) - List of all dynamic content widgets, with usage guides and examples ## Misc -- [Privacy & Security](/privacy) - List of requests, potential issues, and security resources +- [Privacy & Security](/docs/privacy) - List of requests, potential issues, and security resources - [License](/LICENSE) - Copy of the MIT License - [Legal](/.github/LEGAL) - Licenses of direct dependencies - [Code of Conduct](/.github/CODE_OF_CONDUCT) - Contributor Covenant Code of Conduct diff --git a/docs/showcase/readme.md b/docs/showcase/readme.md index 4fcbc8f4..44527bdd 100644 --- a/docs/showcase/readme.md +++ b/docs/showcase/readme.md @@ -1 +1 @@ -See: [Showcase](/showcase). +See: [Showcase](/docs/showcase). diff --git a/docs/status-indicators.md b/docs/status-indicators.md index 80993fc2..9245f42e 100644 --- a/docs/status-indicators.md +++ b/docs/status-indicators.md @@ -1,109 +1,107 @@ -# Status Indicators - -Dashy has an optional feature that can display a small icon next to each of your running services, indicating it's current status. This can be useful if you are using Dashy as your homelab's start page, as it gives you an overview of the health of each of your running services. The status feature will show response time, response code, online/ offline check and if applicable, a relevant error message. - -

- -

- -## Enabling Status Indicators - -By default, this feature is off. If you do not want this feature, just don't add the `statusCheck` to your conf.yml file, then no requests will be made. - -To enable status checks, you can either turn it on for all items, by setting `appConfig.statusCheck: true`, like: - -```yaml -appConfig: - statusCheck: true -``` - -Or you can enable/ disable it on a per-item basis, with the `item[n].statusCheck` attribute - -```yaml -sections: -- name: Firewall - items: - - title: OPNsense - description: Firewall Central Management - icon: networking/opnsense.png - url: https://192.168.1.1 - statusCheck: false - - title: MalTrail - description: Malicious traffic detection system - icon: networking/maltrail.png - url: http://192.168.1.1:8338 - statusCheck: true - - title: Ntopng - description: Network traffic probe and network use monitor - icon: networking/ntop.png - url: http://192.168.1.1:3001 - statusCheck: true -``` - -## Continuous Checking - -By default, with status indicators enabled Dashy will check an applications status on page load, and will not keep indicators updated. This is usually desirable behavior. However, if you do want the status indicators to continue to poll your running services, this can be enabled by setting the `statusCheckInterval` attribute. Here you define an interval as an integer in seconds, and Dashy will poll your apps every x seconds. Note that if this number is very low (below 5 seconds), you may notice the app running slightly slower. - -The following example, will instruct Dashy to continuously check the status of your services every 20 seconds. - -```text -appConfig: - statusCheck: true - statusCheckInterval: 20 -``` - -## Using a Different Endpoint - -By default, the status checker will use the URL of each application being checked. In some situations, you may want to use a different endpoint for status checking. Similarly, some services provide a dedicated path for uptime monitoring. - -You can set the `statusCheckUrl` property on any given item in order to do this. The status checker will then ping that endpoint, instead of the apps main `url` property. - -## Setting Custom Headers - -If your service is responding with an error, despite being up and running, it is most likely because custom headers for authentication, authorization or encoding are required. You can define these headers under the `statusCheckHeaders` property for any service. It should be defined as an object format, with the name of header as the key, and header content as the value. -For example, `statusCheckHeaders: { 'X-Custom-Header': 'foobar' }` - -## Disabling Security - -By default, (if you're using HTTPS) any requests to insecure or non-HTTPS content will be blocked. This will cause the status check to fail. If you trust the endpoint (e.g. you're self-hosting it), then you can disable this security measure for an individual item. This is done by setting `statusCheckAllowInsecure: true` - -## Allowing Alternative Status Codes - -If you expect your service to return a status code that is not in the 2XX range, and still want the indicator to be green, then you can specify an expected status code under `statusCheckAcceptCodes` for a given item. For example, `statusCheckAcceptCodes: '403,418'` - -## Troubleshooting Failing Status Checks - -If you're using status checks, and despite a given service being online, the check is displaying an error, there are a couple of things you can look at: - -If your service requires requests to include any authorization in the headers, then use the `statusCheckHeaders` property, as described [above](#setting-custom-headers). - -If you are still having issues, it may be because your target application is blocking requests from Dashy's IP. This is a [CORS error](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS), and can be fixed by setting the headers on your target app, to include: - -```text -Access-Control-Allow-Origin: https://location-of-dashy/ -Vary: Origin -``` - -If the URL you are checking has an unsigned certificate, or is not using HTTPS, then you may need to disable the rejection of insecure requests. This can be done by setting `statusCheckAllowInsecure` to true for a given item. - -If your service is online, but responds with a status code that is not in the 2xx range, then you can use `statusCheckAcceptCodes` to set an accepted status code. - -If you get an error, like `Service Unavailable: Server resulted in a fatal error`, even when it's definitely online, this is most likely caused by missing the protocol. Don't forget to include `https://` (or whatever protocol) before the URL, and ensure that if needed, you've specified the port. - -Running Dashy in HOST network mode, instead of BRIDGE will allow status check access to other services in HOST mode. For more info, see [#445](https://github.com/Lissy93/dashy/discussions/445). - -If you have firewall rules configured, then ensure that they don't prevent Dashy from making requests to the other services you are trying to access. - -Currently, the status check needs a page to be rendered, so if this URL in your browser does not return anything, then status checks will not work. This may be modified in the future, but in the meantime, a fix would be to make your own status service, which just checks if your app responds with whatever code you'd like, and then return a 200 plus renders an arbitrary message. Then just point `statusCheckUrl` to your custom page. - -For further troubleshooting, use an application like [Postman](https://postman.com) to diagnose the issue. Set the parameter to `GET`, and then make a call to: `https://[url-of-dashy]/status-check/?&url=[service-url]`. Where the service URL must have first been encoded (e.g. with `encodeURIComponent()` or [urlencoder.io](https://www.urlencoder.io/)) - -If you're serving Dashy though a CDN, instead of using the Node server or Docker image, then the Node endpoint that makes requests will not be available to you, and all requests will fail. A workaround for this may be implemented in the future, but in the meantime, your only option is to use the Docker or Node deployment method. - -## How it Works - -When the app is loaded, if `appConfig.statusCheck: true` is set, or if any items have the `statusCheck: true` enabled, then Dashy will make a request, to `https://[your-host-name]/status-check?url=[address-or-servce]` (may al include GET params for headers and the secure flag), which in turn will ping that running service, and respond with a status code. Response time is calculated from the difference between start and end time of the request. - -When the response completes, an indicator will display next to each item. The color denotes the status: Yellow while waiting for the response to return, green if request was successful, red if it failed, and grey if it was unable to make the request all together. - -All requests are made straight from your server, there is no intermediary. So providing you are hosting Dashy yourself, and are checking the status of other self-hosted services, there shouldn't be any privacy concerns. Requests are made asynchronously, so this won't have any significant impact on page load speeds. However recurring requests (using `statusCheckInterval`) may run more slowly if the interval between requests is very short. +# Status Indicators + +Dashy has an optional feature that can display a small icon next to each of your running services, indicating it's current status. This can be useful if you are using Dashy as your homelab's start page, as it gives you an overview of the health of each of your running services. The status feature will show response time, response code, online/ offline check and if applicable, a relevant error message. + + + +## Enabling Status Indicators + +By default, this feature is off. If you do not want this feature, just don't add the `statusCheck` to your conf.yml file, then no requests will be made. + +To enable status checks, you can either turn it on for all items, by setting `appConfig.statusCheck: true`, like: + +```yaml +appConfig: + statusCheck: true +``` + +Or you can enable/ disable it on a per-item basis, with the `item[n].statusCheck` attribute + +```yaml +sections: +- name: Firewall + items: + - title: OPNsense + description: Firewall Central Management + icon: networking/opnsense.png + url: https://192.168.1.1 + statusCheck: false + - title: MalTrail + description: Malicious traffic detection system + icon: networking/maltrail.png + url: http://192.168.1.1:8338 + statusCheck: true + - title: Ntopng + description: Network traffic probe and network use monitor + icon: networking/ntop.png + url: http://192.168.1.1:3001 + statusCheck: true +``` + +## Continuous Checking + +By default, with status indicators enabled Dashy will check an applications status on page load, and will not keep indicators updated. This is usually desirable behavior. However, if you do want the status indicators to continue to poll your running services, this can be enabled by setting the `statusCheckInterval` attribute. Here you define an interval as an integer in seconds, and Dashy will poll your apps every x seconds. Note that if this number is very low (below 5 seconds), you may notice the app running slightly slower. + +The following example, will instruct Dashy to continuously check the status of your services every 20 seconds. + +```text +appConfig: + statusCheck: true + statusCheckInterval: 20 +``` + +## Using a Different Endpoint + +By default, the status checker will use the URL of each application being checked. In some situations, you may want to use a different endpoint for status checking. Similarly, some services provide a dedicated path for uptime monitoring. + +You can set the `statusCheckUrl` property on any given item in order to do this. The status checker will then ping that endpoint, instead of the apps main `url` property. + +## Setting Custom Headers + +If your service is responding with an error, despite being up and running, it is most likely because custom headers for authentication, authorization or encoding are required. You can define these headers under the `statusCheckHeaders` property for any service. It should be defined as an object format, with the name of header as the key, and header content as the value. +For example, `statusCheckHeaders: { 'X-Custom-Header': 'foobar' }` + +## Disabling Security + +By default, (if you're using HTTPS) any requests to insecure or non-HTTPS content will be blocked. This will cause the status check to fail. If you trust the endpoint (e.g. you're self-hosting it), then you can disable this security measure for an individual item. This is done by setting `statusCheckAllowInsecure: true` + +## Allowing Alternative Status Codes + +If you expect your service to return a status code that is not in the 2XX range, and still want the indicator to be green, then you can specify an expected status code under `statusCheckAcceptCodes` for a given item. For example, `statusCheckAcceptCodes: '403,418'` + +## Troubleshooting Failing Status Checks + +If you're using status checks, and despite a given service being online, the check is displaying an error, there are a couple of things you can look at: + +If your service requires requests to include any authorization in the headers, then use the `statusCheckHeaders` property, as described [above](#setting-custom-headers). + +If you are still having issues, it may be because your target application is blocking requests from Dashy's IP. This is a [CORS error](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS), and can be fixed by setting the headers on your target app, to include: + +```text +Access-Control-Allow-Origin: https://location-of-dashy/ +Vary: Origin +``` + +If the URL you are checking has an unsigned certificate, or is not using HTTPS, then you may need to disable the rejection of insecure requests. This can be done by setting `statusCheckAllowInsecure` to true for a given item. + +If your service is online, but responds with a status code that is not in the 2xx range, then you can use `statusCheckAcceptCodes` to set an accepted status code. + +If you get an error, like `Service Unavailable: Server resulted in a fatal error`, even when it's definitely online, this is most likely caused by missing the protocol. Don't forget to include `https://` (or whatever protocol) before the URL, and ensure that if needed, you've specified the port. + +Running Dashy in HOST network mode, instead of BRIDGE will allow status check access to other services in HOST mode. For more info, see [#445](https://github.com/Lissy93/dashy/discussions/445). + +If you have firewall rules configured, then ensure that they don't prevent Dashy from making requests to the other services you are trying to access. + +Currently, the status check needs a page to be rendered, so if this URL in your browser does not return anything, then status checks will not work. This may be modified in the future, but in the meantime, a fix would be to make your own status service, which just checks if your app responds with whatever code you'd like, and then return a 200 plus renders an arbitrary message. Then just point `statusCheckUrl` to your custom page. + +For further troubleshooting, use an application like [Postman](https://postman.com) to diagnose the issue. Set the parameter to `GET`, and then make a call to: `https://[url-of-dashy]/status-check/?&url=[service-url]`. Where the service URL must have first been encoded (e.g. with `encodeURIComponent()` or [urlencoder.io](https://www.urlencoder.io/)) + +If you're serving Dashy though a CDN, instead of using the Node server or Docker image, then the Node endpoint that makes requests will not be available to you, and all requests will fail. A workaround for this may be implemented in the future, but in the meantime, your only option is to use the Docker or Node deployment method. + +## How it Works + +When the app is loaded, if `appConfig.statusCheck: true` is set, or if any items have the `statusCheck: true` enabled, then Dashy will make a request, to `https://[your-host-name]/status-check?url=[address-or-servce]` (may al include GET params for headers and the secure flag), which in turn will ping that running service, and respond with a status code. Response time is calculated from the difference between start and end time of the request. + +When the response completes, an indicator will display next to each item. The color denotes the status: Yellow while waiting for the response to return, green if request was successful, red if it failed, and grey if it was unable to make the request all together. + +All requests are made straight from your server, there is no intermediary. So providing you are hosting Dashy yourself, and are checking the status of other self-hosted services, there shouldn't be any privacy concerns. Requests are made asynchronously, so this won't have any significant impact on page load speeds. However recurring requests (using `statusCheckInterval`) may run more slowly if the interval between requests is very short. diff --git a/docs/theming.md b/docs/theming.md index e15c356f..5bb5a9f0 100644 --- a/docs/theming.md +++ b/docs/theming.md @@ -1,199 +1,197 @@ -# Theming - -By default Dashy comes with 25+ built-in themes, which can be applied from the dropdown menu in the UI. - -![Built-in Themes](https://i.ibb.co/GV3wRss/Dashy-Themes.png) - -You can also add your own themes, apply custom styles, and modify colors. - -You can customize Dashy by writing your own CSS, which can be loaded either as an external stylesheet, set directly through the UI, or specified in the config file. Most styling options can be set through CSS variables, which are outlined below. - -The following content requires that you have a basic understanding of CSS. If you're just beginning, you may find [this article](https://developer.mozilla.org/en-US/docs/Learn/CSS/First_steps) helpful. - -## How Theme-Switching Works - -The theme switching is done by simply changing the `data-theme` attribute on the root DOM element, which can then be targeted by CSS. First off, in order for the theme to show up in the theme switcher, it needs to be added to the config file, under `appConfig.cssThemes`, either as a string, or an array of strings for multiple themes. For example: - -```yaml -appConfig: - cssThemes: ['tiger', 'another-theme'] -``` - -You can now create a block to target you're theme with `html[data-theme='my-theme']{}` and set some styles. The easiest method is by setting CSS variables, but you can also directly override elements by their selector. As an example, see the [built-in CSS themes](https://github.com/Lissy93/dashy/blob/master/src/styles/color-themes.scss). - -```css -html[data-theme='tiger'] { - --primary: #f58233; - --background: #0b1021; -} -``` - -Finally, from the UI use the theme dropdown menu to select your new theme, and your styles will be applied. - -You can also set `appConfig.theme` to pre-select a default theme, which will be applied immediately after deployment. - -## Modifying Theme Colors - -Themes can be modified either through the UI, using the color picker menu (to the right of the theme dropdown), or directly in the config file, under `appConfig.customColors`. Here you can specify the value for any of the [available CSS variables](#css-variables). - -

- - Example Themes - -

- -By default, any color modifications made to the current theme through the UI will only be applied locally. If you need these settings to be set globally, then click the 'Export' button, to get the color codes and variable names, which can then be backed up, or saved in your config file. - -Custom colors are saved relative the the base theme selected. So if you switch themes after setting custom colors, then you're settings will no longer be applied. You're changes are not lost though, and switching back to the original theme will see your styles reapplied. - -If these values are specified in your `conf.yml` file, then it will look something like the below example. Note that in YAML, values or keys which contain special characters, must be wrapped in quotes. - -```yaml -appConfig: - customColors: - oblivion: - primary: '#75efff' - background: '#2a3647' - dracula: - primary: '#8be9fd' -``` - -## Adding your own Theme - -User-defined styles and custom themes should be defined in `./src/styles/user-defined-themes.scss`. If you're using Docker, you can pass your own stylesheet in using the `--volume` flag. E.g. `v ./my-themes.scss:/app/src/styles/user-defined-themes.scss`. Don't forget to pass your theme name into `appConfig.cssThemes` so that it shows up on the theme-switcher dropdown. - -## Setting Custom CSS in the UI - -Custom CSS can be developed, tested and applied directly through the UI. Although you will need to make note of your changes to apply them across instances. - -This can be done from the Config menu (spanner icon in the top-right), under the Custom Styles tab. This is then associated with `appConfig.customCss` in local storage. Styles can also be directly applied to this attribute in the config file, but this may get messy very quickly if you have a lot of CSS. - -## Page-Specific Styles - -If you've got multiple pages within your dashboard, you can choose to target certain styles to specific pages. The top-most element within `` will have a class name specific to the current sub-page. This is usually the page's name, all lowercase, with dashes instead of spaces, but you can easily check this yourself within the dev tools. - -For example, if the pages name was "CFT Toolbox", and you wanted to target `.item`s, you would do: - -```css -.cft-toolbox .item { border: 4px solid yellow; } -``` - -## Loading External Stylesheets - -The URI of a stylesheet, either local or hosted on a remote CDN can be passed into the config file. The attribute `appConfig.externalStyleSheet` accepts either a string, or an array of strings. You can also pass custom font stylesheets here, they must be in a CSS format (for example, `https://fonts.googleapis.com/css2?family=Cutive+Mono`). -This is handled in [`ThemeHelper.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/ThemeHelper.js). - -For example: - -```yaml -appConfig: - externalStyleSheet: 'https://example.com/my-stylesheet.css' -``` - -```yaml -appConfig: - externalStyleSheet: ['/themes/my-theme-1.css', '/themes/my-theme-2.css'] -``` - -## Hard-Coding Section or Item Colors - -Some UI components have a color option, that can be set in the config file, to force the color of a given item or section no matter what theme is selected. These colors should be expressed as hex codes (e.g. `#fff`) or HTML colors (e.g. `red`). The following attributes are supported: - -- `section.color` - Custom color for a given section -- `item.color` - Font and icon color for a given item -- `item.backgroundColor` - Background color for a given icon - -## Typography - -Essential fonts bundled within the app are located within `./src/assets/fonts/`. All optional fonts that are used by themes are stored in `./public/fonts/`, if you want to add your own font, this is where you should put it. As with assets, if you're using Docker then using a volume to link a directory on your host system with this path within the container will make management much easier. - -Fonts which are not being used by the current theme are **not** fetched on page load. They are instead only loaded into the application if and when they are required. So having multiple themes with various typefaces shouldn't have any negative impact on performance. - -Full credit to the typographers behind each of the included fonts. Specifically: Matt McInerney, Christian Robertson, Haley Fiege, Peter Hull, Cyreal and the legendary Vernon Adams - -## CSS Variables - -All colors as well as other variable values (such as borders, border-radius, shadows) are specified as CSS variables. This makes theming the application easy, as you only need to change a given color or value in one place. You can find all variables in [`color-palette.scss`](https://github.com/Lissy93/dashy/blob/master/src/styles/color-palette.scss) and the themes which make use of these color variables are specified in [`color-themes.scss`](https://github.com/Lissy93/dashy/blob/master/src/styles/color-themes.scss) - -CSS variables are simple to use. You define them like: `--background: #fff;` and use them like: `body { background-color: var(--background); }`. For more information, see this guide on using [CSS Variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties). - -You can determine the variable used by any given element, and visualize changes using the browser developer tools (Usually opened with `F12`, or Options --> More --> Developer Tools). Under the elements tab, click the Element Selector icon (usually top-left corner), you will then be able to select any DOM element on the page by hovering and clicking it. In the CSS panel you will see all styles assigned to that given element, including CSS variables. Click a variable to see it's parent value, and for color attributes, click the color square to modify the color. For more information, see this [getting started guide](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/What_are_browser_developer_tools), and these articles on [selecting elements](https://developer.mozilla.org/en-US/docs/Tools/Page_Inspector/How_to/Select_an_element) and [inspecting and modifying colors](https://developer.mozilla.org/en-US/docs/Tools/Page_Inspector/How_to/Inspect_and_select_colors). - -### Top-Level Variables - -These are all that are required to create a theme. All other variables inherit their values from these variables, and can optionally be overridden. - -- `--primary` - Application primary color. Used for title, text, accents, and other features -- `--background` - Application background color -- `--background-darker` - Secondary background color (usually darker), used for navigation bar, section fill, footer etc -- `--curve-factor` - The border radius used globally throughout the application. Specified in `px`, defaults to `5px` -- `--dimming-factor` - Inactive elements have slight transparency. This can be between `0` (invisible) and `1` (normal), defaults to `0.7` - -### Targeted Color Variables - -You can target specific elements on the UI with these variables. All are optional, since by default, they inherit their values from above - -- `--heading-text-color` - Text color for web page heading and sub-heading. Defaults to `--primary` -- `--nav-link-text-color` - The text color for links displayed in the navigation bar. Defaults to `--primary` -- `--nav-link-background-color` - The background color for links displayed in the navigation bar -- `--nav-link-text-color-hover` - The text color when a navigation bar link is hovered over. Defaults to `--primary` -- `--nav-link-background-color-hover` - The background color for nav bar links when hovered over -- `--nav-link-border-color` - The border color for nav bar links. Defaults to `transparent` -- `--nav-link-border-color-hover` - The border color for nav bar links when hovered over. Defaults to `--primary` -- `--search-container-background` - Background for the container containing the search bar. Defaults to `--background-darker` -- `--search-field-background` - Fill color for the search bar. Defaults to `--background` -- `--settings-background` - The background for the quick settings. Defaults to `--background` -- `--settings-text-color` - The text and icon color for quick settings. Defaults to `--primary` -- `--footer-text-color` - Color for text within the footer. Defaults to `--medium-grey` -- `--footer-text-color-link` - Color for any hyperlinks within the footer. Defaults to `--primary` -- `--item-text-color` - The text and icon color for items. Defaults to `--primary` -- `--item-group-outer-background` - The background color for the outer part of a section (including section head). Defaults to `--primary` -- `--item-group-background` - The background color for the inner part of item groups. Defaults to `#0b1021cc` (semi-transparent black) -- `--item-group-heading-text-color` - The text color for section headings. Defaults to `--item-group-background`; -- `--item-group-heading-text-color-hover` - The text color for section headings, when hovered. Defaults to `--background` -- `--config-code-background` - Background color for the JSON editor in the config menu. Defaults to `#fff` (white) -- `--config-code-color` - Text color for the non-highlighted code within the JSON editor. Defaults to `--background` -- `--config-settings-color` - The background for the config/ settings pop-up modal. Defaults to `--primary` -- `--config-settings-background` - The text color for text within the settings container. Defaults to `--background-darker` -- `--scroll-bar-color` - Color of the scroll bar thumb. Defaults to `--primary` -- `--scroll-bar-background` Color of the scroll bar blank space. Defaults to `--background-darker` -- `--highlight-background` Fill color for text highlighting. Defaults to `--primary` -- `--highlight-color` Text color for selected/ highlighted text. Defaults to `--background` -- `--toast-background` - Background color for the toast info popup. Defaults to `--primary` -- `--toast-color` - Text, icon and border color in the toast info popup. Defaults to `--background` -- `--welcome-popup-background` - Background for the info pop-up shown on first load. Defaults to `--background-darker` -- `--welcome-popup-text-color` - Text color for the welcome pop-up. Defaults to `--primary` -- `--side-bar-background` - Background color of the sidebar used in the workspace view. Defaults to `--background-darker` -- `--side-bar-color` - Color of icons and text within the sidebar. Defaults to `--primary` -- `--status-check-tooltip-background` - Background color for status check tooltips. Defaults to `--background-darker` -- `--status-check-tooltip-color` - Text color for the status check tooltips. Defaults to `--primary` -- `--code-editor-color` - Text color used within raw code editors. Defaults to `--black` -- `--code-editor-background` - Background color for raw code editors. Defaults to `--white` -- `--context-menu-color` - Text color for right-click context menu over items. Defaults to `--primary` -- `--context-menu-background` - Background color of right-click context menu. Defaults to `--background` -- `--context-menu-secondary-color` - Border and outline color for context menu. Defaults to `--background-darker` - -### Non-Color Variables - -- `--outline-color` - Used to outline focused or selected elements -- `--curve-factor-navbar` - The border radius of the navbar. Usually this is greater than `--curve-factor` -- `--scroll-bar-width` - Width of horizontal and vertical scroll bars. E.g. `8px` -- `--item-group-padding` - Inner padding of sections, determines the width of outline. E.g. `5px` -- `--item-shadow` - Shadow for items. E.g. `1px 1px 2px #130f23` -- `--item-hover-shadow` - Shadow for items when hovered over. E.g. `1px 2px 4px #373737` -- `--item-icon-transform` - A [transform](https://developer.mozilla.org/en-US/docs/Web/CSS/transform) property, to modify item icons. E.g. `drop-shadow(2px 4px 6px var(--transparent-50)) saturate(0.65)` -- `--item-icon-transform-hover` - Same as above, but applied when an item is hovered over. E.g. `drop-shadow(4px 8px 3px var(--transparent-50)) saturate(2)` -- `--item-group-shadow` - The shadow for an item group/ section. Defaults to `--item-shadow` -- `--settings-container-shadow` - A shadow property for the settings container. E.g. `none` - -### Action Colors - -These colors represent intent, and so are not often changed, but you can do so if you wish - -- `--info` - Information color, usually blue / `#04e4f4` -- `--success` - Success color, usually green / `#20e253` -- `--warning` - Warning color, usually yellow / `#f6f000` -- `--danger` - Error/ danger color, usually red / `#f80363` -- `--neutral` - Neutral color, usually grey / `#272f4d` -- `--white` - Just white / `#fff` -- `--black` - Just black / `#000` +# Theming + +By default Dashy comes with 25+ built-in themes, which can be applied from the dropdown menu in the UI. + +![Built-in Themes](https://i.ibb.co/GV3wRss/Dashy-Themes.png) + +You can also add your own themes, apply custom styles, and modify colors. + +You can customize Dashy by writing your own CSS, which can be loaded either as an external stylesheet, set directly through the UI, or specified in the config file. Most styling options can be set through CSS variables, which are outlined below. + +The following content requires that you have a basic understanding of CSS. If you're just beginning, you may find [this article](https://developer.mozilla.org/en-US/docs/Learn/CSS/First_steps) helpful. + +## How Theme-Switching Works + +The theme switching is done by simply changing the `data-theme` attribute on the root DOM element, which can then be targeted by CSS. First off, in order for the theme to show up in the theme switcher, it needs to be added to the config file, under `appConfig.cssThemes`, either as a string, or an array of strings for multiple themes. For example: + +```yaml +appConfig: + cssThemes: ['tiger', 'another-theme'] +``` + +You can now create a block to target you're theme with `html[data-theme='my-theme']{}` and set some styles. The easiest method is by setting CSS variables, but you can also directly override elements by their selector. As an example, see the [built-in CSS themes](https://github.com/Lissy93/dashy/blob/master/src/styles/color-themes.scss). + +```css +html[data-theme='tiger'] { + --primary: #f58233; + --background: #0b1021; +} +``` + +Finally, from the UI use the theme dropdown menu to select your new theme, and your styles will be applied. + +You can also set `appConfig.theme` to pre-select a default theme, which will be applied immediately after deployment. + +## Modifying Theme Colors + +Themes can be modified either through the UI, using the color picker menu (to the right of the theme dropdown), or directly in the config file, under `appConfig.customColors`. Here you can specify the value for any of the [available CSS variables](#css-variables). + + + Example Themes + + +By default, any color modifications made to the current theme through the UI will only be applied locally. If you need these settings to be set globally, then click the 'Export' button, to get the color codes and variable names, which can then be backed up, or saved in your config file. + +Custom colors are saved relative the the base theme selected. So if you switch themes after setting custom colors, then you're settings will no longer be applied. You're changes are not lost though, and switching back to the original theme will see your styles reapplied. + +If these values are specified in your `conf.yml` file, then it will look something like the below example. Note that in YAML, values or keys which contain special characters, must be wrapped in quotes. + +```yaml +appConfig: + customColors: + oblivion: + primary: '#75efff' + background: '#2a3647' + dracula: + primary: '#8be9fd' +``` + +## Adding your own Theme + +User-defined styles and custom themes should be defined in `./src/styles/user-defined-themes.scss`. If you're using Docker, you can pass your own stylesheet in using the `--volume` flag. E.g. `v ./my-themes.scss:/app/src/styles/user-defined-themes.scss`. Don't forget to pass your theme name into `appConfig.cssThemes` so that it shows up on the theme-switcher dropdown. + +## Setting Custom CSS in the UI + +Custom CSS can be developed, tested and applied directly through the UI. Although you will need to make note of your changes to apply them across instances. + +This can be done from the Config menu (spanner icon in the top-right), under the Custom Styles tab. This is then associated with `appConfig.customCss` in local storage. Styles can also be directly applied to this attribute in the config file, but this may get messy very quickly if you have a lot of CSS. + +## Page-Specific Styles + +If you've got multiple pages within your dashboard, you can choose to target certain styles to specific pages. The top-most element within `` will have a class name specific to the current sub-page. This is usually the page's name, all lowercase, with dashes instead of spaces, but you can easily check this yourself within the dev tools. + +For example, if the pages name was "CFT Toolbox", and you wanted to target `.item`s, you would do: + +```css +.cft-toolbox .item { border: 4px solid yellow; } +``` + +## Loading External Stylesheets + +The URI of a stylesheet, either local or hosted on a remote CDN can be passed into the config file. The attribute `appConfig.externalStyleSheet` accepts either a string, or an array of strings. You can also pass custom font stylesheets here, they must be in a CSS format (for example, `https://fonts.googleapis.com/css2?family=Cutive+Mono`). +This is handled in [`ThemeHelper.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/ThemeHelper.js). + +For example: + +```yaml +appConfig: + externalStyleSheet: 'https://example.com/my-stylesheet.css' +``` + +```yaml +appConfig: + externalStyleSheet: ['/themes/my-theme-1.css', '/themes/my-theme-2.css'] +``` + +## Hard-Coding Section or Item Colors + +Some UI components have a color option, that can be set in the config file, to force the color of a given item or section no matter what theme is selected. These colors should be expressed as hex codes (e.g. `#fff`) or HTML colors (e.g. `red`). The following attributes are supported: + +- `section.color` - Custom color for a given section +- `item.color` - Font and icon color for a given item +- `item.backgroundColor` - Background color for a given icon + +## Typography + +Essential fonts bundled within the app are located within `./src/assets/fonts/`. All optional fonts that are used by themes are stored in `./public/fonts/`, if you want to add your own font, this is where you should put it. As with assets, if you're using Docker then using a volume to link a directory on your host system with this path within the container will make management much easier. + +Fonts which are not being used by the current theme are **not** fetched on page load. They are instead only loaded into the application if and when they are required. So having multiple themes with various typefaces shouldn't have any negative impact on performance. + +Full credit to the typographers behind each of the included fonts. Specifically: Matt McInerney, Christian Robertson, Haley Fiege, Peter Hull, Cyreal and the legendary Vernon Adams + +## CSS Variables + +All colors as well as other variable values (such as borders, border-radius, shadows) are specified as CSS variables. This makes theming the application easy, as you only need to change a given color or value in one place. You can find all variables in [`color-palette.scss`](https://github.com/Lissy93/dashy/blob/master/src/styles/color-palette.scss) and the themes which make use of these color variables are specified in [`color-themes.scss`](https://github.com/Lissy93/dashy/blob/master/src/styles/color-themes.scss) + +CSS variables are simple to use. You define them like: `--background: #fff;` and use them like: `body { background-color: var(--background); }`. For more information, see this guide on using [CSS Variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties). + +You can determine the variable used by any given element, and visualize changes using the browser developer tools (Usually opened with `F12`, or Options --> More --> Developer Tools). Under the elements tab, click the Element Selector icon (usually top-left corner), you will then be able to select any DOM element on the page by hovering and clicking it. In the CSS panel you will see all styles assigned to that given element, including CSS variables. Click a variable to see it's parent value, and for color attributes, click the color square to modify the color. For more information, see this [getting started guide](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/What_are_browser_developer_tools), and these articles on [selecting elements](https://developer.mozilla.org/en-US/docs/Tools/Page_Inspector/How_to/Select_an_element) and [inspecting and modifying colors](https://developer.mozilla.org/en-US/docs/Tools/Page_Inspector/How_to/Inspect_and_select_colors). + +### Top-Level Variables + +These are all that are required to create a theme. All other variables inherit their values from these variables, and can optionally be overridden. + +- `--primary` - Application primary color. Used for title, text, accents, and other features +- `--background` - Application background color +- `--background-darker` - Secondary background color (usually darker), used for navigation bar, section fill, footer etc +- `--curve-factor` - The border radius used globally throughout the application. Specified in `px`, defaults to `5px` +- `--dimming-factor` - Inactive elements have slight transparency. This can be between `0` (invisible) and `1` (normal), defaults to `0.7` + +### Targeted Color Variables + +You can target specific elements on the UI with these variables. All are optional, since by default, they inherit their values from above + +- `--heading-text-color` - Text color for web page heading and sub-heading. Defaults to `--primary` +- `--nav-link-text-color` - The text color for links displayed in the navigation bar. Defaults to `--primary` +- `--nav-link-background-color` - The background color for links displayed in the navigation bar +- `--nav-link-text-color-hover` - The text color when a navigation bar link is hovered over. Defaults to `--primary` +- `--nav-link-background-color-hover` - The background color for nav bar links when hovered over +- `--nav-link-border-color` - The border color for nav bar links. Defaults to `transparent` +- `--nav-link-border-color-hover` - The border color for nav bar links when hovered over. Defaults to `--primary` +- `--search-container-background` - Background for the container containing the search bar. Defaults to `--background-darker` +- `--search-field-background` - Fill color for the search bar. Defaults to `--background` +- `--settings-background` - The background for the quick settings. Defaults to `--background` +- `--settings-text-color` - The text and icon color for quick settings. Defaults to `--primary` +- `--footer-text-color` - Color for text within the footer. Defaults to `--medium-grey` +- `--footer-text-color-link` - Color for any hyperlinks within the footer. Defaults to `--primary` +- `--item-text-color` - The text and icon color for items. Defaults to `--primary` +- `--item-group-outer-background` - The background color for the outer part of a section (including section head). Defaults to `--primary` +- `--item-group-background` - The background color for the inner part of item groups. Defaults to `#0b1021cc` (semi-transparent black) +- `--item-group-heading-text-color` - The text color for section headings. Defaults to `--item-group-background`; +- `--item-group-heading-text-color-hover` - The text color for section headings, when hovered. Defaults to `--background` +- `--config-code-background` - Background color for the JSON editor in the config menu. Defaults to `#fff` (white) +- `--config-code-color` - Text color for the non-highlighted code within the JSON editor. Defaults to `--background` +- `--config-settings-color` - The background for the config/ settings pop-up modal. Defaults to `--primary` +- `--config-settings-background` - The text color for text within the settings container. Defaults to `--background-darker` +- `--scroll-bar-color` - Color of the scroll bar thumb. Defaults to `--primary` +- `--scroll-bar-background` Color of the scroll bar blank space. Defaults to `--background-darker` +- `--highlight-background` Fill color for text highlighting. Defaults to `--primary` +- `--highlight-color` Text color for selected/ highlighted text. Defaults to `--background` +- `--toast-background` - Background color for the toast info popup. Defaults to `--primary` +- `--toast-color` - Text, icon and border color in the toast info popup. Defaults to `--background` +- `--welcome-popup-background` - Background for the info pop-up shown on first load. Defaults to `--background-darker` +- `--welcome-popup-text-color` - Text color for the welcome pop-up. Defaults to `--primary` +- `--side-bar-background` - Background color of the sidebar used in the workspace view. Defaults to `--background-darker` +- `--side-bar-color` - Color of icons and text within the sidebar. Defaults to `--primary` +- `--status-check-tooltip-background` - Background color for status check tooltips. Defaults to `--background-darker` +- `--status-check-tooltip-color` - Text color for the status check tooltips. Defaults to `--primary` +- `--code-editor-color` - Text color used within raw code editors. Defaults to `--black` +- `--code-editor-background` - Background color for raw code editors. Defaults to `--white` +- `--context-menu-color` - Text color for right-click context menu over items. Defaults to `--primary` +- `--context-menu-background` - Background color of right-click context menu. Defaults to `--background` +- `--context-menu-secondary-color` - Border and outline color for context menu. Defaults to `--background-darker` + +### Non-Color Variables + +- `--outline-color` - Used to outline focused or selected elements +- `--curve-factor-navbar` - The border radius of the navbar. Usually this is greater than `--curve-factor` +- `--scroll-bar-width` - Width of horizontal and vertical scroll bars. E.g. `8px` +- `--item-group-padding` - Inner padding of sections, determines the width of outline. E.g. `5px` +- `--item-shadow` - Shadow for items. E.g. `1px 1px 2px #130f23` +- `--item-hover-shadow` - Shadow for items when hovered over. E.g. `1px 2px 4px #373737` +- `--item-icon-transform` - A [transform](https://developer.mozilla.org/en-US/docs/Web/CSS/transform) property, to modify item icons. E.g. `drop-shadow(2px 4px 6px var(--transparent-50)) saturate(0.65)` +- `--item-icon-transform-hover` - Same as above, but applied when an item is hovered over. E.g. `drop-shadow(4px 8px 3px var(--transparent-50)) saturate(2)` +- `--item-group-shadow` - The shadow for an item group/ section. Defaults to `--item-shadow` +- `--settings-container-shadow` - A shadow property for the settings container. E.g. `none` + +### Action Colors + +These colors represent intent, and so are not often changed, but you can do so if you wish + +- `--info` - Information color, usually blue / `#04e4f4` +- `--success` - Success color, usually green / `#20e253` +- `--warning` - Warning color, usually yellow / `#f6f000` +- `--danger` - Error/ danger color, usually red / `#f80363` +- `--neutral` - Neutral color, usually grey / `#272f4d` +- `--white` - Just white / `#fff` +- `--black` - Just black / `#000` diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 895d1e1f..c98e05b0 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -119,7 +119,7 @@ If you're seeing Dashy's 404 page on initial load/ refresh, and then the main ap The first solution is to switch the routing mode, from HTML5 `history` mode to `hash` mode, by setting `appConfig.routingMode` to `hash`. -If this works, but you wish to continue using HTML5 history mode, then a bit of extra [server configuration](/management.md#web-server-configuration) is required. This is explained in more detaail in the [Vue Docs](https://router.vuejs.org/guide/essentials/history-mode.html). Once completed, you can then use `routingMode: history` again, for neater URLs. +If this works, but you wish to continue using HTML5 history mode, then a bit of extra [server configuration](/docs/management.md#web-server-configuration) is required. This is explained in more detaail in the [Vue Docs](https://router.vuejs.org/guide/essentials/history-mode.html). Once completed, you can then use `routingMode: history` again, for neater URLs. --- @@ -156,7 +156,7 @@ If you're getting an error about scenarios, then you've likely installed the wro Alternatively, as a workaround, you have several options: - Try using [NPM](https://www.npmjs.com/get-npm) instead: So clone, cd, then run `npm install`, `npm run build` and `npm start` -- Try using [Docker](https://www.docker.com/get-started) instead, and all of the system setup and dependencies will already be taken care of. So from within the directory, just run `docker build -t lissy93/dashy .` to build, and then use docker start to run the project, e.g: `docker run -it -p 8080:8080 lissy93/dashy` (see the [deploying docs](/docs/deployment#deploy-with-docker) for more info) +- Try using [Docker](https://www.docker.com/get-started) instead, and all of the system setup and dependencies will already be taken care of. So from within the directory, just run `docker build -t lissy93/dashy .` to build, and then use docker start to run the project, e.g: `docker run -it -p 8080:8080 lissy93/dashy` (see the [deploying docs](/docs/deployment.md#deploy-with-docker) for more info) --- @@ -244,7 +244,7 @@ volumes: Check the [browser's console output](#how-to-open-browser-console), if you've not set any headers, you will likely see a CORS error here, which would be the source of the issue. -You need to allow Dashy to make requests to Keycloak, and Keycloak to redirect to Dashy. The way you do this depends on how you're hosting these applications / which proxy you are using, and examples can be found in the [Management Docs](/management.md#setting-headers). +You need to allow Dashy to make requests to Keycloak, and Keycloak to redirect to Dashy. The way you do this depends on how you're hosting these applications / which proxy you are using, and examples can be found in the [Management Docs](/docs/management.md#setting-headers). For example, add the access control header to Keycloak, like: @@ -254,7 +254,7 @@ Note that for requests that transport sensitive info like credentials, setting t You should also ensure that Keycloak is correctly configured, with a user, realm and application, and be sure that you have set a valid redirect URL in Keycloak ([screenshot](https://user-images.githubusercontent.com/1862727/148599768-db4ee4f8-72c5-402d-8f00-051d999e6267.png)). -For more details on how to set headers, see the [Example Headers](/management.md#setting-headers) in the management docs, or reference the documentation for your proxy. +For more details on how to set headers, see the [Example Headers](/docs/management.md#setting-headers) in the management docs, or reference the documentation for your proxy. If you're running in Kubernetes, you will need to enable CORS ingress rules, see [docs](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#enable-cors), e.g: @@ -400,7 +400,7 @@ Run `sudo apt install gnupg2 pass && gpg2 -k` If you're using status checks, and despite a given service being online, the check is displaying an error, there are a couple of things you can look at: -If your service requires requests to include any authorization in the headers, then use the `statusCheckHeaders` property, as described in the [docs](/status-indicators.md#setting-custom-headers). +If your service requires requests to include any authorization in the headers, then use the `statusCheckHeaders` property, as described in the [docs](/docs/status-indicators.md#setting-custom-headers). If you are still having issues, it may be because your target application is blocking requests from Dashy's IP. This is a [CORS error](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS), and can be fixed by setting the headers on your target app, to include: @@ -431,7 +431,7 @@ If you're serving Dashy though a CDN, instead of using the Node server or Docker ### Find Error Message -If an error occurs when fetching or rendering results, you will see a short message in the UI. If that message doesn't adequately explain the problem, then you can [open the browser console](/troubleshooting.md#how-to-open-browser-console) to see more details. +If an error occurs when fetching or rendering results, you will see a short message in the UI. If that message doesn't adequately explain the problem, then you can [open the browser console](/docs/troubleshooting.md#how-to-open-browser-console) to see more details. ### Check Config @@ -439,7 +439,7 @@ Before proceeding, ensure that if the widget requires auth your API is correct, ### Timeout Error -If the error message in the console includes: `Error: timeout of 500ms exceeded`, then your Glances endpoint is slower to respond than expected. You can fix this by [setting timeout](/docs/widgets#setting-timeout) to a larger value. This is done on each widget, with the `timeout` attribute, and is specified in ms. E.g. `timeout: 5000` would only fail if no response is returned within 5 seconds. +If the error message in the console includes: `Error: timeout of 500ms exceeded`, then your Glances endpoint is slower to respond than expected. You can fix this by [setting timeout](/docs/widgets.md#setting-timeout) to a larger value. This is done on each widget, with the `timeout` attribute, and is specified in ms. E.g. `timeout: 5000` would only fail if no response is returned within 5 seconds. ### CORS error @@ -476,11 +476,11 @@ or Access-Control-Allow-Origin: * ``` -For more info on how to set headers, see: [Setting Headers](/management.md#setting-headers) in the management docs +For more info on how to set headers, see: [Setting Headers](/docs/management.md#setting-headers) in the management docs ### Option 3 - Proxying Request -You can route requests through Dashy's built-in CORS proxy. Instructions and more details can be found [here](/widgets.md#proxying-requests). If you don't have control over the target origin, and you are running Dashy either through Docker, with the Node server or on Netlify, then this solution will work for you. +You can route requests through Dashy's built-in CORS proxy. Instructions and more details can be found [here](/docs/widgets.md#proxying-requests). If you don't have control over the target origin, and you are running Dashy either through Docker, with the Node server or on Netlify, then this solution will work for you. Just add the `useProxy: true` option to the failing widget. @@ -503,13 +503,13 @@ If this is the case, you can disable the UI error message of a given widget by s A 401 error means your API key is invalid, it is not an issue with Dashy. -Usually this happens due to an error in your config. If you're unsure, copy and paste the [example](/widgets.md#weather) config, replacing the API key with your own. +Usually this happens due to an error in your config. If you're unsure, copy and paste the [example](/docs/widgets.md#weather) config, replacing the API key with your own. Check that `apiKey` is correctly specified, and nested within `options`. Ensure your input city is valid. To test your API key, try making a request to `https://api.openweathermap.org/data/2.5/weather?q=London&appid=[your-api-key]` -If [Weather widget](/widgets.md#weather-forecast) is working fine, but you are getting a `401` for the [Weather Forecast widget](/widgets.md#weather-forecast), then this is also an OWM API key issue. +If [Weather widget](/docs/widgets.md#weather-forecast) is working fine, but you are getting a `401` for the [Weather Forecast widget](/docs/widgets.md#weather-forecast), then this is also an OWM API key issue. Since the forecasting API requires an upgraded plan. ULPT: You can get a free, premium API key by filling in [this form](https://home.openweathermap.org/students). It's a student plan, but there's no verification to check that you are still a student. A future update will be pushed out, to use a free weather forecasting API. @@ -524,7 +524,7 @@ If any widget is not displaying the data you expect, first confirm that your con If the raw API output is correct, yet the widget is rendering incorrect results, then it is likely a bug, and a ticket should be raised. You can start to debug the issue, by looking at the widget's code ([here](https://github.com/Lissy93/dashy/tree/master/src/components/Widgets)), and the browser console + networking tab. -If the API itself is returning incorrect, incomplete or inaccurate data then an issue needs to be raised **with the API provider** (not Dashy!). You can find the API provider included within the widget docs, or for a full list see the [Privacy Docs](/docs/privacy#widgets). +If the API itself is returning incorrect, incomplete or inaccurate data then an issue needs to be raised **with the API provider** (not Dashy!). You can find the API provider included within the widget docs, or for a full list see the [Privacy Docs](/docs/privacy.md#widgets). See also: [#807](https://github.com/Lissy93/dashy/issues/807) (re, domain monitor) @@ -532,7 +532,7 @@ See also: [#807](https://github.com/Lissy93/dashy/issues/807) (re, domain monito ## Font Awesome Icons not Displaying -Usually, Font Awesome will be automatically enabled if one or more of your icons are using Font-Awesome. If this is not happening, then you can always manually enable (or disable) Font Awesome by setting: [`appConfig`](/configuring.md#appconfig-optional).`enableFontAwesome` to `true`. +Usually, Font Awesome will be automatically enabled if one or more of your icons are using Font-Awesome. If this is not happening, then you can always manually enable (or disable) Font Awesome by setting: [`appConfig`](/docs/configuring.md#appconfig-optional).`enableFontAwesome` to `true`. If you are trying to use a premium icon, then you must have a [Pro License](https://fontawesome.com/plans). You'll then need to specify your Pro plan API key under `appConfig.fontAwesomeKey`. You can find this key, by logging into your FA account, navigate to Account โ†’ [Kits](https://fontawesome.com/kits) โ†’ New Kit โ†’ Copy Kit Code. The code is a 10-digit alpha-numeric code, and is also visible within the new kit's URL, for example: `81e48ce079`. @@ -556,7 +556,7 @@ The most common reason for this, is if you not running the app over HTTPS. Copyi As a workaround, you could either: - Highlight the text and copy / Ctrl + C -- Or setup SSL - [here's a guide](/docs/management#ssl-certificates) on doing so +- Or setup SSL - [here's a guide](/docs/management.md#ssl-certificates) on doing so --- @@ -584,7 +584,7 @@ This will not affect your config file. But be sure that you keep a backup of you You can also view any and all data that Dashy is storing, using the developer tools. Open your browser's dev tools (usually F12), in Chromium head to the Application tab, or in Firefox go to the Storage tab. Select Local Storage, then scroll down the the URL Dashy is running on. You should now see all data being stored, and you can select and delete any fields you wish. -For a full list of all data that may be cached, see the [Privacy Docs](/privacy.md#browser-storage). +For a full list of all data that may be cached, see the [Privacy Docs](/docs/privacy.md#browser-storage). --- diff --git a/docs/widgets.md b/docs/widgets.md index 0b585c16..88f452ec 100644 --- a/docs/widgets.md +++ b/docs/widgets.md @@ -70,8 +70,10 @@ Dashy has support for displaying dynamic content in the form of widgets. There a - [Sabnzbd](#sabnzbd) - [Gluetun VPN Info](#gluetun-vpn-info) - [Drone CI Build](#drone-ci-builds) + - [Filebrowser](#filebrowser) - [Linkding](#linkding) - [Uptime Kuma](#uptime-kuma) + - [Uptime Kuma Status Page](#uptime-kuma-status-page) - [Tactical RMM](#tactical-rmm) - **[System Resource Monitoring](#system-resource-monitoring)** - [CPU Usage Current](#current-cpu-usage) @@ -1491,6 +1493,7 @@ Allows web search using multiple user-defined search engines and other websites. --- | --- | --- | --- **`engines`** | `array` | required | An array of search engine objects. Each search engine object should have two required properties: **title** and **url**. See the example below. **`placeholder`** | `string` | optional | Placeholder text in the search box. +**`openingMethod`** | `string` | optional | Open search in one of `newtab`, `sametab` or `workspace`. #### Notes - The first search engine in the engines array will be treated as the default search engine, and used when the user presses `Enter` in the search box. @@ -2599,6 +2602,77 @@ Display the last builds from a [Drone CI](https://www.drone.ci) instance. A self --- +### Filebrowser + +Displays storage statistics and file listings from a [Filebrowser Quantum](https://github.com/gtsteffaniak/filebrowser) instance. Shows directory size, file/folder counts, favorite files, and recently modified files with quick-access links. + +#### Options + +**Field** | **Type** | **Required** | **Description** +--- | --- | --- | --- +**`hostname`** | `string` | Required | The URL of your Filebrowser instance +**`apiKey`** | `string` | Required | A long-lived API key (create in Settings โ†’ API Keys) +**`source`** | `string` | _Optional_ | The source/scope name to browse. Defaults to the first available source +**`path`** | `string` | _Optional_ | The directory path to display. Defaults to `/` +**`favorites`** | `array` | _Optional_ | List of filenames to show as quick-access favorites +**`showRecent`** | `number` | _Optional_ | Number of recently modified files to display. Defaults to `5`, set to `0` to disable +**`limit`** | `number` | _Optional_ | Maximum number of files to display per section. Defaults to `10` +**`hideStats`** | `boolean` | _Optional_ | If `true`, hides the storage statistics section +**`hideFavorites`** | `boolean` | _Optional_ | If `true`, hides the favorites section +**`hideRecent`** | `boolean` | _Optional_ | If `true`, hides the recent files section +**`showDetailedStats`** | `boolean` | _Optional_ | If `true`, shows additional statistics including last modified date, largest file, hidden file count, total items, and file type breakdown. Defaults to `false` + +#### Example + +**Basic usage:** + +```yaml +- type: filebrowser + useProxy: true + options: + hostname: http://filebrowser.local:8080 + apiKey: VUE_APP_FILEBROWSER_KEY + source: Documents + path: / + showRecent: 5 + favorites: + - important-notes.txt + - config.yaml +``` + +**With detailed statistics:** + +```yaml +- type: filebrowser + useProxy: true + options: + hostname: http://filebrowser.local:8080 + apiKey: VUE_APP_FILEBROWSER_KEY + source: Downloads + showDetailedStats: true + showRecent: 10 + limit: 15 +``` + +#### Widget Sections + +The widget displays up to four sections: + +1. **Storage Stats** - Directory name, total size, file and folder counts +2. **Detailed Stats** (optional) - Last modified date, largest file, hidden file count, total items, and file type breakdown with badges +3. **Favorites** - Quick-access links to user-specified files +4. **Recent Files** - Most recently modified files sorted by date + +#### Info + +- **CORS**: ๐ŸŸ  Proxied +- **Auth**: ๐ŸŸข Required +- **Price**: ๐ŸŸข Free +- **Host**: Self-Hosted (see [Filebrowser Quantum](https://github.com/gtsteffaniak/filebrowser)) +- **Privacy**: _Self-Hosted_ + +--- + ### Linkding Linkding is a self-hosted bookmarking service, which has a clean interface and is simple to set up. This lists the links, filterable by tags. @@ -2665,6 +2739,40 @@ Linkding is a self-hosted bookmarking service, which has a clean interface and i --- +### Uptime Kuma Status Page + +[Uptime Kuma](https://github.com/louislam/uptime-kuma) is an easy-to-use self-hosted monitoring tool. + +#### Options + +| **Field** | **Type** | **Required** | **Description** | +| ------------------ | -------- | ------------ | --------------------------------------------------------------------------------- | +| **`host`** | `string` | Required | The URL of the Uptime Kuma instance | +| **`slug`** | `string` | Required | The slug of the status page | +| **`monitorNames`** | `strins` | _Optional_ | Names of monitored services (in the same order as on the kuma uptime status page) | + +#### Example + +```yaml +- type: uptime-kuma-status-page + options: + host: http://localhost:3001 + slug: another-beautiful-status-page + monitorNames: + - "Name1" + - "Name2" +``` + +#### Info + +- **CORS**: ๐ŸŸข Enabled +- **Auth**: ๐ŸŸข Not Needed +- **Price**: ๐ŸŸข Free +- **Host**: Self-Hosted (see [Uptime Kuma](https://github.com/louislam/uptime-kuma) ) +- **Privacy**: _See [Uptime Kuma](https://github.com/louislam/uptime-kuma)_ + +--- + ### Tactical RMM [Tactical RMM](https://github.com/amidaware/tacticalrmm) is a self-hosted remote monitoring & management tool. @@ -3229,7 +3337,7 @@ You can do this, by setting the environmental variable name as the value, instea The key can be named whatever you like, but it must start with `VUE_APP_` (to be picked up by Vue). If you need to update any of these values, a rebuild is required (this can be done under the Config menu in the UI, or by running `yarn build` then restarting the container). -For more infomation about setting and managing your environmental variables, see [Management Docs --> Environmental Variables](/management.md#passing-in-environmental-variables). +For more infomation about setting and managing your environmental variables, see [Management Docs --> Environmental Variables](/docs/management.md#passing-in-environmental-variables). For example: @@ -3312,7 +3420,7 @@ Widgets use the following color variables, which can be overridden if desired: - `--widget-background-color` - Background color, defaults to `--background-darker` - `--widget-accent-color` - Accent color, defaults to `--background` -For more info on how to apply custom variables, see the [Theming Docs](/theming.md#setting-custom-css-in-the-ui) +For more info on how to apply custom variables, see the [Theming Docs](/docs/theming.md#setting-custom-css-in-the-ui) --- @@ -3338,7 +3446,7 @@ Since most of the content displayed within widgets is fetched from an external A However, any hard-coded content is translatable, and all dates and times will display in your local format. -For more info about multi-language support, see the [Internationalization Docs](/multi-language-support). +For more info about multi-language support, see the [Internationalization Docs](/docs/multi-language-support). --- @@ -3348,7 +3456,7 @@ Widgets can be opened in full-page view, by clicking the Arrow icon (top-right). You can reload the data of any widget, by clicking the Refresh Data icon (also in top-right). This will only affect the widget where the action was triggered from. -All [config options](/configuring.md#section) that can be applied to sections, can also be applied to widget sections. For example, to make a widget section double the width, set `displayData.cols: 2` within the parent section. You can collapse a widget (by clicking the section title), and collapse state will be saved locally. +All [config options](/docs/configuring.md#section) that can be applied to sections, can also be applied to widget sections. For example, to make a widget section double the width, set `displayData.cols: 2` within the parent section. You can collapse a widget (by clicking the section title), and collapse state will be saved locally. Widgets cannot currently be edited through the UI. This feature is in development, and will be released soon. In the meantime, you can either use the JSON config editor, or use [VS Code Server](https://github.com/coder/code-server), or just SSH into your box and edit the conf.yml file directly. @@ -3358,7 +3466,7 @@ Widgets cannot currently be edited through the UI. This feature is in developmen Widgets are built in a modular fashion, making it easy for anyone to create their own custom components. -For a full tutorial on creating your own widget, you can follow [this guide](/development-guides.md/#building-a-widget), or take a look at [here](https://github.com/Lissy93/dashy/commit/3da76ce2999f57f76a97454c0276301e39957b8e) for a code example. +For a full tutorial on creating your own widget, you can follow [this guide](/docs/development-guides.md/#building-a-widget), or take a look at [here](https://github.com/Lissy93/dashy/commit/3da76ce2999f57f76a97454c0276301e39957b8e) for a code example. Alternatively, for displaying simple data, you could also just use the either the [iframe](#iframe-widget), [embed](#html-embedded-widget), [data feed](#data-feed) or [API response](#api-response) widgets. @@ -3378,13 +3486,13 @@ Please only request widgets for services that: You can suggest a widget [here](https://git.io/Jygo3), please star the repo before submitting a ticket. If you are a monthly GitHub sponsor, I will happily build out a custom widget for any service that meets the above criteria, usually within 2 weeks of initial request. -For services that are not officially supported, it is likely still possible to display data using either the [iframe](#iframe-widget), [embed](#html-embedded-widget) or [API response](#api-response) widgets. For more advanced features, like charts and action buttons, you could also build your own widget, using [this tutorial](/development-guides.md/#building-a-widget), it's fairly straight forward, and you can use an [existing widget](https://github.com/Lissy93/dashy/tree/master/src/components/Widgets) (or [this example](https://git.io/JygKI)) as a template. +For services that are not officially supported, it is likely still possible to display data using either the [iframe](#iframe-widget), [embed](#html-embedded-widget) or [API response](#api-response) widgets. For more advanced features, like charts and action buttons, you could also build your own widget, using [this tutorial](/docs/development-guides.md/#building-a-widget), it's fairly straight forward, and you can use an [existing widget](https://github.com/Lissy93/dashy/tree/master/src/components/Widgets) (or [this example](https://git.io/JygKI)) as a template. --- ### Troubleshooting Widget Errors -If an error occurs when fetching or rendering results, you will see a short message in the UI. If that message doesn't adequately explain the problem, then you can [open the browser console](/troubleshooting.md#how-to-open-browser-console) to see more details. +If an error occurs when fetching or rendering results, you will see a short message in the UI. If that message doesn't adequately explain the problem, then you can [open the browser console](/docs/troubleshooting.md#how-to-open-browser-console) to see more details. Before proceeding, ensure that if the widget requires auth your API is correct, and for custom widgets, double check that the URL and protocol is correct. @@ -3429,4 +3537,4 @@ For testing purposes, you can use an addon, which will disable the CORS checks. ### Raising an Issue -If you need to submit a bug report for a failing widget, then please include the full console output (see [how](/troubleshooting.md#how-to-open-browser-console)) as well as the relevant parts of your config file. Before sending the request, ensure you've read the docs. If you're new to GitHub, an haven't previously contributed to the project, then please fist star the repo to avoid your ticket being closed by the anti-spam bot. +If you need to submit a bug report for a failing widget, then please include the full console output (see [how](/docs/troubleshooting.md#how-to-open-browser-console)) as well as the relevant parts of your config file. Before sending the request, ensure you've read the docs. If you're new to GitHub, an haven't previously contributed to the project, then please fist star the repo to avoid your ticket being closed by the anti-spam bot. diff --git a/docusaurus.config.js b/docusaurus.config.js index 1ef3d33b..9ef36bd0 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -29,18 +29,12 @@ module.exports = { // Dark & Light Mode colorMode: { defaultMode: 'dark', - switchConfig: { - darkIcon: '๐ŸŒ™', - lightIcon: 'โ˜€๏ธ', - }, }, // Algolia Web Search algolia: { apiKey: '97d967bd42096f2c69f015214ff36176', indexName: 'main', - // contextualSearch: true, - // appId: '9NYB4LE3DS', - // searchParameters: {}, + appId: '9NYB4LE3DS', }, // Prism Code Highlighting prism: { @@ -116,9 +110,9 @@ module.exports = { items: [ { label: 'Privacy & Security', to: '/docs/privacy' }, { label: 'License', to: '/docs/license' }, - { label: 'Legal', to: 'https://github.com/Lissy93/dashy/blob/master/.github/LEGAL.md' }, - { label: 'Code of Conduct', to: '/docs/code-of-conduct' }, - { label: 'Changelog', to: '/docs/changelog' }, + { label: 'Legal', href: 'https://github.com/Lissy93/dashy/blob/master/.github/LEGAL.md' }, + { label: 'Code of Conduct', href: 'https://github.com/Lissy93/dashy/blob/master/.github/CODE_OF_CONDUCT.md' }, + { label: 'Changelog', href: 'https://github.com/Lissy93/dashy/blob/master/.github/CHANGELOG.md' }, ], }, ], diff --git a/package.json b/package.json index 03935739..f640d1b0 100644 --- a/package.json +++ b/package.json @@ -14,19 +14,19 @@ "write-heading-ids": "docusaurus write-heading-ids" }, "dependencies": { - "@docusaurus/core": "2.0.0-beta.2", - "@docusaurus/preset-classic": "2.0.0-beta.2", - "@docusaurus/theme-search-algolia": "^2.0.0-beta.5", - "@mdx-js/react": "^1.6.21", - "@svgr/webpack": "^5.5.0", - "clsx": "^1.1.1", - "docusaurus-plugin-sass": "^0.2.1", - "file-loader": "^6.2.0", - "prism-react-renderer": "^1.2.1", - "react": "^17.0.1", - "react-dom": "^17.0.1", - "sass": "^1.35.1", - "url-loader": "^4.1.1" + "@docusaurus/core": "^2.4.3", + "@docusaurus/preset-classic": "^2.4.3", + "@docusaurus/theme-search-algolia": "^2.4.3", + "@mdx-js/react": "^1.6.22", + "clsx": "^1.2.1", + "docusaurus-plugin-sass": "^0.2.6", + "prism-react-renderer": "^1.3.5", + "react": "^17.0.2", + "react-dom": "^17.0.2", + "sass": "^1.97.1" + }, + "devDependencies": { + "@docusaurus/module-type-aliases": "^2.4.3" }, "browserslist": { "production": [ @@ -39,5 +39,12 @@ "last 1 firefox version", "last 1 safari version" ] + }, + "engines": { + "node": ">=16.14" + }, + "overrides": { + "undici": "^5.28.4", + "cheerio": "1.0.0-rc.12" } } diff --git a/src/theme/DocSidebar/index.js b/src/theme/DocSidebar/index.js deleted file mode 100644 index 76dd38f2..00000000 --- a/src/theme/DocSidebar/index.js +++ /dev/null @@ -1,353 +0,0 @@ -/** - * Copyright (c) Facebook, Inc. and its affiliates. - * - * This source code is licensed under the MIT license found in the - * LICENSE file in the root directory of this source tree. - */ -import React, {useState, useCallback, useEffect, useRef, memo} from 'react'; -import clsx from 'clsx'; -import { - useThemeConfig, - isSamePath, - usePrevious, - useAnnouncementBar, -} from '@docusaurus/theme-common'; -import useLockBodyScroll from '@theme/hooks/useLockBodyScroll'; -import useWindowSize, {windowSizes} from '@theme/hooks/useWindowSize'; -import useScrollPosition from '@theme/hooks/useScrollPosition'; -import Link from '@docusaurus/Link'; -import isInternalUrl from '@docusaurus/isInternalUrl'; -import Logo from '@theme/Logo'; -import IconArrow from '@theme/IconArrow'; -import IconMenu from '@theme/IconMenu'; -import IconExternalLink from '@theme/IconExternalLink'; -import {translate} from '@docusaurus/Translate'; -import styles from './styles.module.css'; -import CarbonAds from '../../components/CarbonAd'; -const MOBILE_TOGGLE_SIZE = 24; - -const isActiveSidebarItem = (item, activePath) => { - if (item.type === 'link') { - return isSamePath(item.href, activePath); - } - - if (item.type === 'category') { - return item.items.some((subItem) => - isActiveSidebarItem(subItem, activePath), - ); - } - - return false; -}; // Optimize sidebar at each "level" -// TODO this item should probably not receive the "activePath" props -// TODO this triggers whole sidebar re-renders on navigation - -const DocSidebarItems = memo(function DocSidebarItems({items, ...props}) { - return items.map((item, index) => ( - - )); -}); - -function DocSidebarItem(props) { - switch (props.item.type) { - case 'category': - return ; - - case 'link': - default: - return ; - } -} - -function DocSidebarItemCategory({ - item, - onItemClick, - collapsible, - activePath, - ...props -}) { - const {items, label} = item; - const isActive = isActiveSidebarItem(item, activePath); - const wasActive = usePrevious(isActive); // active categories are always initialized as expanded - // the default (item.collapsed) is only used for non-active categories - - const [collapsed, setCollapsed] = useState(() => { - if (!collapsible) { - return false; - } - - return isActive ? false : item.collapsed; - }); - const menuListRef = useRef(null); - const [menuListHeight, setMenuListHeight] = useState(undefined); - - const handleMenuListHeight = (calc = true) => { - setMenuListHeight( - calc ? `${menuListRef.current?.scrollHeight}px` : undefined, - ); - }; // If we navigate to a category, it should automatically expand itself - - useEffect(() => { - const justBecameActive = isActive && !wasActive; - - if (justBecameActive && collapsed) { - setCollapsed(false); - } - }, [isActive, wasActive, collapsed]); - const handleItemClick = useCallback( - (e) => { - e.preventDefault(); - - if (!menuListHeight) { - handleMenuListHeight(); - } - - setTimeout(() => setCollapsed((state) => !state), 100); - }, - [menuListHeight], - ); - - if (items.length === 0) { - return null; - } - - return ( -
  • - - {label} - -
      { - if (!collapsed) { - handleMenuListHeight(false); - } - }}> - -
    -
    • - ); -} - -function DocSidebarItemLink({ - item, - onItemClick, - activePath, - collapsible: _collapsible, - ...props -}) { - const {href, label} = item; - const isActive = isActiveSidebarItem(item, activePath); - return ( -
  • - - {isInternalUrl(href) ? ( - label - ) : ( - - {label} - - - )} - -
    • - ); -} - -function useShowAnnouncementBar() { - const {isClosed} = useAnnouncementBar(); - const [showAnnouncementBar, setShowAnnouncementBar] = useState(!isClosed); - useScrollPosition(({scrollY}) => { - if (!isClosed) { - setShowAnnouncementBar(scrollY === 0); - } - }); - return showAnnouncementBar; -} - -function useResponsiveSidebar() { - const [showResponsiveSidebar, setShowResponsiveSidebar] = useState(false); - useLockBodyScroll(showResponsiveSidebar); - const windowSize = useWindowSize(); - useEffect(() => { - if (windowSize === windowSizes.desktop) { - setShowResponsiveSidebar(false); - } - }, [windowSize]); - const closeResponsiveSidebar = useCallback( - (e) => { - e.target.blur(); - setShowResponsiveSidebar(false); - }, - [setShowResponsiveSidebar], - ); - const toggleResponsiveSidebar = useCallback(() => { - setShowResponsiveSidebar((value) => !value); - }, [setShowResponsiveSidebar]); - return { - showResponsiveSidebar, - closeResponsiveSidebar, - toggleResponsiveSidebar, - }; -} - -function HideableSidebarButton({onClick}) { - return ( - - ); -} - -function ResponsiveSidebarButton({responsiveSidebarOpened, onClick}) { - return ( - - ); -} - -function DocSidebar({ - path, - sidebar, - sidebarCollapsible = true, - onCollapse, - isHidden, -}) { - const showAnnouncementBar = useShowAnnouncementBar(); - const { - navbar: {hideOnScroll}, - hideableSidebar, - } = useThemeConfig(); - const {isClosed: isAnnouncementBarClosed} = useAnnouncementBar(); - const { - showResponsiveSidebar, - closeResponsiveSidebar, - toggleResponsiveSidebar, - } = useResponsiveSidebar(); - return ( -
    - {hideOnScroll && } - -
    - {hideableSidebar && } -
    - ); -} - -export default DocSidebar; diff --git a/src/theme/DocSidebar/styles.module.css b/src/theme/DocSidebar/styles.module.css deleted file mode 100644 index 6dcbbfb1..00000000 --- a/src/theme/DocSidebar/styles.module.css +++ /dev/null @@ -1,150 +0,0 @@ -/** - * Copyright (c) Facebook, Inc. and its affiliates. - * - * This source code is licensed under the MIT license found in the - * LICENSE file in the root directory of this source tree. - */ - -:root { - --collapse-button-bg-color-dark: #2e333a; -} - -@media (min-width: 997px) { - .sidebar { - display: flex; - flex-direction: column; - max-height: 100vh; - height: 100%; - position: sticky; - top: 0; - padding-top: var(--ifm-navbar-height); - width: var(--doc-sidebar-width); - transition: opacity 50ms ease; - } - - .sidebarWithHideableNavbar { - padding-top: 0; - } - - .sidebarHidden { - opacity: 0; - height: 0; - overflow: hidden; - visibility: hidden; - } - - .sidebarLogo { - display: flex !important; - align-items: center; - margin: 0 var(--ifm-navbar-padding-horizontal); - min-height: var(--ifm-navbar-height); - max-height: var(--ifm-navbar-height); - color: inherit !important; - text-decoration: none !important; - } - - .sidebarLogo img { - margin-right: 0.5rem; - height: 2rem; - } - - .menu { - flex-grow: 1; - padding: 0.5rem; - } - - .menuLinkText { - cursor: initial; - } - - .menuLinkText:hover { - background: none; - } - - .menuWithAnnouncementBar { - margin-bottom: var(--docusaurus-announcement-bar-height); - } - - .collapseSidebarButton { - display: block !important; - background-color: var(--ifm-button-background-color); - height: 40px; - position: sticky; - bottom: 0; - border-radius: 0; - border: 1px solid var(--ifm-toc-border-color); - } - - .collapseSidebarButtonIcon { - transform: rotate(180deg); - margin-top: 4px; - } - html[dir='rtl'] .collapseSidebarButtonIcon { - transform: rotate(0); - } - - html[data-theme='dark'] .collapseSidebarButton { - background-color: var(--collapse-button-bg-color-dark); - } - - html[data-theme='dark'] .collapseSidebarButton:hover, - html[data-theme='dark'] .collapseSidebarButton:focus { - background-color: var(--ifm-color-emphasis-200); - } -} - -.sidebarLogo, -.collapseSidebarButton { - display: none; -} - -.sidebarMenuIcon { - vertical-align: middle; -} - -.sidebarMenuCloseIcon { - display: inline-flex; - justify-content: center; - align-items: center; - height: 24px; - font-size: 1.5rem; - font-weight: var(--ifm-font-weight-bold); - line-height: 0.9; - width: 24px; -} - -:global(.menu__list) :global(.menu__list) { - overflow-y: hidden; - will-change: height; - transition: height var(--ifm-transition-fast) linear; -} - -:global(.menu__list-item--collapsed) :global(.menu__list) { - height: 0 !important; -} - -.sidebar-ad { - --carbon-bg-primary: var(--background, #18191a); - --carbon-bg-secondary: #282a36; - --carbon-text-color: #e6e6e6; -} - -.sidebar-ad #carbonads { - margin: 0.5rem; -} -.sidebar-ad #carbonads .carbon-img img, .sidebar-ad .avatar__photo-link { - border-radius: 5px; -} -.sidebar-ad #carbonads .carbon-wrap { - justify-content: center; -} -.sidebar-ad #carbonads .carbon-text { - font-size: 1rem; -} -.sidebar-ad #carbonads > span { - box-shadow: none; -} -.sidebar-ad #carbonads .carbon-poweredby { - border-radius: 5px; - font-size: 0.7rem; -}