docs: add documentation for custom themes (streetwriters#3118)

* themebuilder: add docs * themebuilder: update theme docs * docs: finalize docs for custom themes --------- Co-authored-by: ammarahm-ed <ammarahmed6506@gmail.com>
nimdassdev · Aug 9, 2023 · 49455e8 · 49455e8
1 parent 1136e43
commit 49455e8
Show file tree

Hide file tree

Showing 46 changed files with 326 additions and 1 deletion.
diff --git a/docs/help/contents/_include/custom-themes/Screenshot_20230808-173716.png b/docs/help/contents/_include/custom-themes/Screenshot_20230808-173716.png
diff --git a/docs/help/contents/_include/custom-themes/theme-scope-context-menu.png b/docs/help/contents/_include/custom-themes/theme-scope-context-menu.png
diff --git a/docs/help/contents/_include/custom-themes/theme-scope-dialog.png b/docs/help/contents/_include/custom-themes/theme-scope-dialog.png
diff --git a/docs/help/contents/_include/custom-themes/theme-scope-editor-sidebar.png b/docs/help/contents/_include/custom-themes/theme-scope-editor-sidebar.png
diff --git a/docs/help/contents/_include/custom-themes/theme-scope-editor-toolbar.png b/docs/help/contents/_include/custom-themes/theme-scope-editor-toolbar.png
diff --git a/docs/help/contents/_include/custom-themes/theme-scope-editor.png b/docs/help/contents/_include/custom-themes/theme-scope-editor.png
diff --git a/docs/help/contents/_include/custom-themes/theme-scope-list.png b/docs/help/contents/_include/custom-themes/theme-scope-list.png
diff --git a/docs/help/contents/_include/custom-themes/theme-scope-navigation-menu.png b/docs/help/contents/_include/custom-themes/theme-scope-navigation-menu.png
diff --git a/docs/help/contents/_include/custom-themes/theme-scope-sheet.png b/docs/help/contents/_include/custom-themes/theme-scope-sheet.png
diff --git a/docs/help/contents/_include/custom-themes/theme-scope-status-bar.png b/docs/help/contents/_include/custom-themes/theme-scope-status-bar.png
diff --git a/docs/help/contents/_include/custom-themes/theme-scopes-schema.png b/docs/help/contents/_include/custom-themes/theme-scopes-schema.png
diff --git a/docs/help/contents/_include/custom.css b/docs/help/contents/_include/custom.css
@@ -159,8 +159,11 @@ html.dark {
   --input-border: #383838;
   --input-bg: #151515;
 }
+nav li {
+  line-height: 24px;
+}
 
-nav li:not(li.nested):hover {
+nav li li:not(li.nested):hover {
   background-color: var(--hover-bg);
 }
 

diff --git a/docs/help/contents/_include/publish-theme-1.png b/docs/help/contents/_include/publish-theme-1.png
diff --git a/docs/help/contents/_include/publish-theme-10.png b/docs/help/contents/_include/publish-theme-10.png
diff --git a/docs/help/contents/_include/publish-theme-2.png b/docs/help/contents/_include/publish-theme-2.png
diff --git a/docs/help/contents/_include/publish-theme-3.png b/docs/help/contents/_include/publish-theme-3.png
diff --git a/docs/help/contents/_include/publish-theme-4.png b/docs/help/contents/_include/publish-theme-4.png
diff --git a/docs/help/contents/_include/publish-theme-5.png b/docs/help/contents/_include/publish-theme-5.png
diff --git a/docs/help/contents/_include/publish-theme-6.png b/docs/help/contents/_include/publish-theme-6.png
diff --git a/docs/help/contents/_include/publish-theme-7.png b/docs/help/contents/_include/publish-theme-7.png
diff --git a/docs/help/contents/_include/publish-theme-8.png b/docs/help/contents/_include/publish-theme-8.png
diff --git a/docs/help/contents/_include/publish-theme-9.png b/docs/help/contents/_include/publish-theme-9.png
diff --git a/docs/help/contents/_include/theme-builder-actions.png b/docs/help/contents/_include/theme-builder-actions.png
diff --git a/docs/help/contents/_include/theme-builder-base.png b/docs/help/contents/_include/theme-builder-base.png
diff --git a/docs/help/contents/_include/theme-builder-change-color.gif b/docs/help/contents/_include/theme-builder-change-color.gif
diff --git a/docs/help/contents/_include/theme-builder-export-theme.png b/docs/help/contents/_include/theme-builder-export-theme.png
diff --git a/docs/help/contents/_include/theme-builder-metadata.png b/docs/help/contents/_include/theme-builder-metadata.png
diff --git a/docs/help/contents/_include/theme-builder-navigation-menu-modify.png b/docs/help/contents/_include/theme-builder-navigation-menu-modify.png
diff --git a/docs/help/contents/_include/theme-builder-navigation-menu-scope.png b/docs/help/contents/_include/theme-builder-navigation-menu-scope.png
diff --git a/docs/help/contents/_include/theme-builder-navigation-menu.png b/docs/help/contents/_include/theme-builder-navigation-menu.png
diff --git a/docs/help/contents/_include/theme-builder-select-starter-theme.png b/docs/help/contents/_include/theme-builder-select-starter-theme.png
diff --git a/docs/help/contents/_include/theme-builder.png b/docs/help/contents/_include/theme-builder.png
diff --git a/docs/help/contents/_include/theme-load-file.png b/docs/help/contents/_include/theme-load-file.png
diff --git a/docs/help/contents/_include/theme-set-as-default.png b/docs/help/contents/_include/theme-set-as-default.png
diff --git a/docs/help/contents/_include/update-theme-1.png b/docs/help/contents/_include/update-theme-1.png
diff --git a/docs/help/contents/_include/update-theme-2.png b/docs/help/contents/_include/update-theme-2.png
diff --git a/docs/help/contents/_include/update-theme-3.png b/docs/help/contents/_include/update-theme-3.png
diff --git a/docs/help/contents/_include/update-theme-4.png b/docs/help/contents/_include/update-theme-4.png
diff --git a/docs/help/contents/_include/update-theme-5.png b/docs/help/contents/_include/update-theme-5.png
diff --git a/docs/help/contents/_include/update-theme-6.png b/docs/help/contents/_include/update-theme-6.png
diff --git a/docs/help/contents/custom-themes/README.md b/docs/help/contents/custom-themes/README.md
@@ -0,0 +1 @@
+# Custom themes
diff --git a/docs/help/contents/custom-themes/create-a-theme-with-theme-builder.md b/docs/help/contents/custom-themes/create-a-theme-with-theme-builder.md
@@ -0,0 +1,95 @@
+# Create a theme with the Theme Builder
+
+The Theme Builder provides an easy and accessible way to create themes for Notesnook without prior technical knowledge. The purpose of this tool is to allow anyone, especially a layman, to tweak Notesnook according to their liking.
+
+You can access the Theme Builder at [https://theme-builder.notesnook.com](https://theme-builder.notesnook.com).
+
+> info
+>
+> The Theme Builder is the exact duplicate of the Notesnook Web application — just with the option to tweak the colors. You can use it to sign into your account, create notes, and everything else you do in the Notesnook app.
+
+Here's a look at the theme builder:
+
+![Toolbar](/theme-builder.png)
+
+Now let's walk through the whole process of creating your own theme using the Theme Builder.
+
+## 1. Select a starter theme
+
+Before you can create your own theme, it is best to select a starter theme to build upon. This allows us to quickly visualize all the changes without have to build from scratch.
+
+The Theme Builder makes this very easy:
+
+1. Open the [Theme Builder](https://theme-builder.notesnook.com).
+2. Go to `Settings > Appearance > Themes` and select any theme from the list.
+
+> warn
+>
+> Keep in mind that a theme can only have one color scheme: `light` or `dark` so choose your starter theme accordingly.
+
+For our example, we are going to select "Notesnook Light" as our base theme.
+
+![Toolbar](/theme-builder-select-starter-theme.png)
+
+Once the theme is applied, you'll notice all the colors in the Theme Builder update with the colors of the Notesnook Light theme.
+
+## 2. Setting theme metadata
+
+Theme metadata allows better discoverability in search and gives users a quick idea of what the theme is. You can read about all the supported properties [here](/custom-themes/introduction#theme-metadata).
+
+![Toolbar](/theme-builder-metadata.png)
+
+> warn Theme ID conflicts
+>
+> Remember that the `id` for your custom theme should not conflict with other published themes on Notesnook. You can see the list of all published theme IDs [here](https://github.com/streetwriters/notesnook-themes/tree/main/themes).
+
+## 3. Configuring base theme scope
+
+> info
+>
+> Before you proceed, it is recommended that you [learn about how theming in Notesnook works](/custom-themes/introduction#what-is-a-theme), what scopes, variants & colors do etc.
+
+Every Notesnook theme must implement the base theme scope. Colors from the `base` theme scope are used as a fallback in all other scopes if a specific color is not defined.
+
+![Toolbar](/theme-builder-base.png)
+
+For our example, we will be creating a Blue accented theme for Notesnook. In order to do that, we must replace all the occurences of the default green color (#008837) in the `base` theme scope with a nice blue color (#1d4ed8).
+
+Since we want to create a blue variant of our Notesnook light theme, we will replace the default green (#008837) in our base theme scope with blue(#1d4ed8). We have to go through all variants, primary, secondary, selected, disabled and replace the colors.
+
+![Toolbar](/theme-builder-change-color.gif)
+
+As you change each color, you will see the changes reflected in the app in real-time. How cool is that!
+
+## 4. Configuring optional scopes
+
+After configuring `base` theme scope, you can optionally set colors for other scopes, such as `navigationMenu`, to make them look a little different.
+
+> info An example
+>
+> For example, in the default Notesnook Light theme, the background color of the navigation menu is grayish instead of pure white.
+>
+> ![Toolbar](/theme-builder-navigation-menu.png)
+>
+> This is because the default Notesnook Light theme has a different background color set for the `navigationMenu` scope.
+>
+> ![Toolbar](/theme-builder-navigation-menu-scope.png)
+
+The sky is the limit here. In most cases, though, the `base` scope will suffice unless you want to get super creative like me.
+
+![Toolbar](/theme-builder-navigation-menu-modify.png)
+
+And that's it! Your theme is ready to be exported.
+
+## 5. Exporting your theme
+
+Once you have finished working on your theme, you can export it by clicking the "Export theme" button at the top of Theme Builder pane.
+
+![](/theme-builder-export-theme.png)
+
+You will get a JSON file containing your theme which you can either [install directly into the Notesnook app](/custom-themes/install-a-theme-from-file) for personal use or [publish it](/custom-themes/publish-a-theme) for others to use as well.
+
+## Further reading
+
+- [Publish your theme](/custom-themes/publish-a-theme)
+- [Install a theme directly from JSON file](/custom-themes/install-a-theme-from-file)
diff --git a/docs/help/contents/custom-themes/install-a-theme-from-file.md b/docs/help/contents/custom-themes/install-a-theme-from-file.md
@@ -0,0 +1,11 @@
+## Install a theme directly from theme.json file
+
+In both mobile and desktop/web apps, you can install themes directly from a JSON theme file.
+
+1. Open the Notesnook app
+2. Go to Settings > Appearance > Themes
+3. Click on "Load from file" button
+   ![Toolbar](/theme-load-file.png)
+4. Select the JSON file to load the theme from.
+5. Click on "Set as default"\
+   ![](/theme-set-as-default.png)
diff --git a/docs/help/contents/custom-themes/introduction.md b/docs/help/contents/custom-themes/introduction.md
@@ -0,0 +1,153 @@
+# Introduction
+
+> info
+>
+> This document reflects v1.0 of the Notesnook Theme specification.
+
+The goal of this document is to provide you with an exact idea of what each scope, variant & color in the theme does, how they all fit together, and how you can use them to create your own custom theme for Notesnook. This document will also serve as a descriptive guide for any `theme.json` file you may find online.
+
+## What is a theme?
+
+Even though Notesnook's theming engine is quite flexible, there _are_ limits to it. In Notesnook, a theme is like a skin: while you can change the colors of it, there's no way to change other properties like size & layout. In other words, your theme will only affect the colors of UI elements like background color, text color, border color and so on.
+
+But the question is, how granular can you get? Notesnook already had accent colors which allowed switching between 9 different "themes". Is that the extent of customization allowed by the new theming engine or is there more? What are the possibilities?
+
+Suffice it to say, you can change every part of Notesnook independently. This is made possible with the help of 3 things.
+
+### 1. Scopes
+
+Scopes allow you to independently theme various parts of the Notesnook app.
+Each scope represents a specific part of the app. For example, you can style the editor toolbar different than the rest of the UI. Since scopes never overlap with each other, you can style each part of Notesnook without worrying about the rest.
+
+Here's a quick schematic diagram of each scope used by the Notesnook Web app.
+
+![](/custom-themes/theme-scopes-schema.png)
+
+Currently, Notesnook has 10 scopes:
+
+#### 1. `base`
+
+The `base` scope is the only required scope in a Notesnook theme. It must have all its variants & colors specified. `base` scope acts as the fallback for all other scopes. For example, if a Notesnook client cannot find a color in the `statusBar` scope, it'll automatically take it from the `base` scope.
+
+Here's an incomplete list of areas that always use the `base` scope:
+
+1. Web clipper
+2. Login/sign up screens
+3. Email confirmation screen
+4. Settings (on mobile)
+
+This allows you to change only the colors you need without any duplication.
+
+#### 2. `navigationMenu`
+
+The `navigationMenu` scope is used by the left-most side bar that contains the links to your Notes, Notebooks, Favorites etc.
+
+![](/custom-themes/theme-scope-navigation-menu.png)
+
+#### 3. `statusBar`
+
+The `statusBar` scope is used by the bottom most horizontal bar that contains your email address, the sync status etc.
+
+![](/custom-themes/theme-scope-status-bar.png)
+
+#### 4. `list`
+
+The `list` scope is used by the list of notes, notebooks & everything else that is in the middle pane.
+
+![](/custom-themes/theme-scope-list.png)
+
+#### 5. `editor`
+
+The `editor` scope is used by the editor and everything inside of it like task lists, outline lists, tables etc. This scope does not include the editor toolbar.
+
+![](/custom-themes/theme-scope-editor.png)
+
+#### 6. `editorToolbar`
+
+The `editorToolbar` scope is used specifically by the editor toolbar for styling all its icons, buttons & menus.
+
+![](/custom-themes/theme-scope-editor-toolbar.png)
+
+#### 7. `editorSidebar`
+
+The `editorSidebar` scope is used by the right-most properties menu, and the PDF attachments preview.
+
+![](/custom-themes/theme-scope-editor-sidebar.png)
+
+#### 8. `dialog`
+
+All the dialogs in the app, regardless of how they are triggered or what they contain, use the `dialog` scope. This includes the settings dialog, notebook creation dialog, reminder creation dialog etc.
+
+![](/custom-themes/theme-scope-dialog.png)
+
+#### 9. `contextMenu`
+
+All the context menus & drop down menus in the app use the `contextMenu` scope. This includes the menus in the `editor`, `list`, and other scopes.
+
+![](/custom-themes/theme-scope-context-menu.png)
+
+#### 10. `sheet`
+
+The `sheet` scope is a mobile specific scope, and is not used by the web app. It is used by all the popup action sheets displayed in the mobile app.
+
+<img src="/custom-themes/theme-scope-sheet.png" height="500px"/>
+
+---
+
+Each scope is further broken down into Variants.
+
+### 2. Variants
+
+Variants reflect either the state or importance of a UI element. Variants are NOT isolated and can be intermixed so it is important for a theme to have good contrast between the colors of each variant in order to avoid making some parts of Notesnook completely unreadable.
+
+Currently, Notesnook has 5 variants:
+
+1. `primary`
+   \
+   The `primary` variant is used by every element when it isn't in any of the other states.
+2. `secondary`
+   \
+   The `secondary` variant is complimentary to the `primary` variant. It is used in places to show elements or text of less importance. For example, the text `12h ago` shown under each note item uses the `paragraph` color from the `secondary` variant.
+3. `selected`
+   \
+   This variant is used throughout the app for all elements in selected, toggled, or focused state.
+4. `error`
+   \
+   The `error` variant contains colors for showing errored status anywhere inside the app. It is possible that the UI element using this variant may make use of colors from other variants.
+5. `success`
+   \
+   The `success` variant contains colors for showing success status anywhere inside the app. It is possible that the UI element using this variant may make use of colors from other variants.
+
+Each variant further contains a total of 12 Colors:
+
+| Color           | Description                                                                                                        | Transparent |
+| --------------- | ------------------------------------------------------------------------------------------------------------------ | ----------- |
+| `accent`        | Color used to make something stand out (like the primary button in dialogs). Can be both background or foreground. | ❌          |
+| `shade`         | Color used as a background to show prominence.                                                                     | ✅          |
+| `background`    | Background color of elements                                                                                       | ❌          |
+| `paragraph`     | Color of paragraphs and other text                                                                                 | ❌          |
+| `heading`       | Color of headings &amp; titles                                                                                     | ❌          |
+| `backdrop`      | The color of the overlay shown behind dialogs &amp; modals                                                         | ✅          |
+| `textSelection` | The text color of selected text                                                                                    | ✅          |
+| `hover`         | Background color when hovering over elements (that support it)                                                     | ✅          |
+| `border`        | Border color                                                                                                       | ❌          |
+| `separator`     | Color of the separator line between items                                                                          | ❌          |
+| `placeholder`   | Color of the placeholder in input fields                                                                           | ❌          |
+| `icon`          | Color of icons                                                                                                     | ❌          |
+
+### Theme Metadata
+
+1. `name`: the name of the theme
+2. `description`: a short description of the theme
+3. `id`: a unique alphanumeric id of the theme. Must be unique across all other themes.
+4. `version`: version of the theme (you must increment this on every new change of the theme)
+5. `authors`: one or more authors of the theme.
+6. `compatibilityVersion`: The compatibility version of the theme used by the client to decide whether the theme is supported by the current client version.
+7. `license`: the license under which the theme can be shared, modified etc.
+8. `homepage`: website or homepage of the theme
+9. `colorScheme`: "light" or "dark"
+10. `tags`: keywords to help categorize the theme & improve search results.
+
+## Further reading
+
+- [Build your own theme using the Theme Builder](/custom-themes/create-a-theme-with-theme-builder).
diff --git a/docs/help/contents/custom-themes/publish-a-theme.md b/docs/help/contents/custom-themes/publish-a-theme.md
@@ -0,0 +1,56 @@
+# Publish a new theme
+
+## Prerequisites
+
+1. A [GitHub](https://github.com/) account
+2. JSON file containing your theme (you can export the JSON file [using the Theme Builder](/custom-themes/create-a-theme-with-theme-builder))
+
+## Instructions
+
+1. Go to [https://github.com/streetwriters/notesnook-themes](https://github.com/streetwriters/notesnook-themes) and "Fork" the repo. (Don't forget to "Star" it as well!)\
+   ![Toolbar](/publish-theme-1.png)
+2. Click on the "Create fork" button on the next page.\
+   ![Toolbar](/publish-theme-2.png)
+3. Once your fork has been created, go to the `themes/` directory and create a new file.\
+   ![Toolbar](/publish-theme-3.png)
+4. Enter the path for your file as `{your-theme-id}/v1/theme.json`. (Pressing `/` will create a new directory.)\
+   ![Toolbar](/publish-theme-4.png)
+5. Paste the contents of the JSON theme file and click on "Commit changes".
+   ![Toolbar](/publish-theme-5.png)
+6. Enter title of your commit as "add {your-theme-id} theme"
+7. Click on "Commit changes"
+   ![Toolbar](/publish-theme-6.png)
+8. On the next page, click on "Contribute" and then click on "Open pull request" from the popup.
+   ![Toolbar](/publish-theme-7.png)
+9. Click on "Create pull request"
+   ![Toolbar](/publish-theme-8.png)
+10. Click on "Create pull request"
+    ![Toolbar](/publish-theme-9.png)
+11. And you are all done!
+    ![Toolbar](/publish-theme-10.png)
+
+# Updating your theme
+
+Once your theme is published, you will probably need to push a new update for your theme to fix a color or change something. You can do this by [selecting your theme as the starter theme](/custom-themes/create-a-theme-with-theme-builder#1-select-a-starter-theme) in the Theme Builder and making the changes. Once everything is ready, just [export the changed theme](/custom-themes/create-a-theme-with-theme-builder#5-exporting-your-theme) as usual.
+
+> warn
+>
+> Don't forget to increment the version of your theme; otherwise, no one will be able to see the changes.
+
+To publish the updated theme, you will need to submit a new pull request in the same way as you did while publishing:
+
+1. Go to your fork on GitHub. (Mine is at [https://github.com/ammarahm-ed/notesnook-themes](https://github.com/ammarahm-ed/notesnook-themes)).
+2. Click on "Sync fork" and then click the "Update branch" button.
+   ![Toolbar](/update-theme-1.png)
+3. Go to `themes/your-theme-id/v1` directory and open the `theme.json` file.
+4. Click on the Edit button\
+   ![Toolbar](/update-theme-2.png)
+5. Paste your updated theme and click on "Commit changes".
+6. Enter title of your commit as `update {your-theme-id} theme` and click on "Commit changes".
+   ![Toolbar](/update-theme-3.png)
+7. Now go to the homepage of your fork and click on "Contribute" and then click on "Open pull request" in the popup.
+   ![Toolbar](/update-theme-4.png)
+8. Click on "Create pull request"
+   ![Toolbar](/update-theme-5.png)
+9. You are all done!
+   ![Toolbar](/update-theme-6.png)
diff --git a/docs/help/docgen.yaml b/docs/help/docgen.yaml
@@ -73,3 +73,9 @@ navigation:
       - path: desktop-integration/jumplist-and-dock-menu.md
       - path: desktop-integration/spell-checker.md
       - path: desktop-integration/system-tray-menu.md
+  - path: custom-themes
+    children:
+      - path: custom-themes/introduction.md
+      - path: custom-themes/create-a-theme-with-theme-builder.md
+      - path: custom-themes/install-a-theme-from-file.md
+      - path: custom-themes/publish-a-theme.md