|
| 1 | +# Custom CSS |
| 2 | + |
| 3 | +!!! warning |
| 4 | + |
| 5 | + Custom CSS is a feature for advanced users. There is no official support for customizations, and you perform any customizations at your own risk. In case something goes wrong, you can simply remove the `custom.css` from the Zettlr data directory to reset the custom CSS again. |
| 6 | + |
| 7 | +It is possible to use custom CSS ([Cascading Style Sheets](https://en.wikipedia.org/wiki/Cascading_Style_Sheets)) to modify the complete appearance of the app. You can find the Custom CSS editor in the [assets manager](./assets-manager.md). |
| 8 | + |
| 9 | +!!! warning |
| 10 | + |
| 11 | + The examples in this document haven't been updated in some time, so they may not work out of the box. |
| 12 | + |
| 13 | +If you are unfamiliar with CSS, but don't want to simply copy & paste the guides on this page, you may choose to follow a short [tutorial on CSS](https://developer.mozilla.org/en-US/docs/Learn/CSS/Introduction_to_CSS). There are many on the internet, so a quick Google search can also provide you with video tutorials, if you prefer those. |
| 14 | + |
| 15 | +## Writing CSS for Zettlr |
| 16 | + |
| 17 | +The styles of Zettlr are divided into both geometry and the actual theme, so you may want to stick with only changing the design of elements _without_ changing **any** geometry. Playing around with the geometry may be fun, but it may yield completely random behaviour, as some parts of the app depend upon the correct sizes of elements. In case you made a mistake, don't worry: Simply remove the `custom.css` file from the data directory of Zettlr. You can find the data directory of your own system by looking at the paths provided in [the setup guide](../getting-started/setup.md). |
| 18 | + |
| 19 | +Classes and IDs in Zettlr are always namespaced to the respective components (unless they're global), so to really override a rule you will have to use the complete namespace (you can also use the `!important` override rule, but this is widely regarded as bad practice). |
| 20 | + |
| 21 | +Everything is always namespaced to the `body`, which has a class `.dark` if the app is currently in dark mode. So to make sure a certain rule only applies while the app is in dark mode, make sure to prefix it with `body.dark`! |
| 22 | + |
| 23 | +## Tips for finding selectors |
| 24 | + |
| 25 | +Zettlr's styles are subject to constant changes. While they should remain fairly stable, changes can be introduced in any version, and therefore, instead of providing you with ready-made examples, this page covers how you can find the correct selectors easily. |
| 26 | + |
| 27 | +First of all, make sure to enable the debug mode in the advanced [preferences](../reference/settings.md) in order to enable the Develop menu. Next, open the developer tools from within this menu and make sure to select the "Elements" tab. |
| 28 | + |
| 29 | + |
| 30 | + |
| 31 | +Then click the arrow in the top-left corner of the developer tools. Now you can click any element in the application to focus it in the developer tools. In the bottom area of the developer tools, you will then see the CSS directives used to style all elements of this particular shape. |
| 32 | + |
| 33 | + |
| 34 | + |
| 35 | +The top rules always override the bottom rules, so what you are interested in is the following directive: |
| 36 | + |
| 37 | +```css |
| 38 | +body .cm-quote, body .cm-link, body .cm-strong, body .cm-em { |
| 39 | + color: var(--c-primary); |
| 40 | +} |
| 41 | +``` |
| 42 | + |
| 43 | +This is the selector you want to copy over to your custom CSS dialog and style to your liking. As you can see, it gives blockquotes, links, bold and italic text the primary color of the theme. |
| 44 | + |
| 45 | +## CSS Code Snippets |
| 46 | + |
| 47 | +### Using a Custom Font with Zettlr |
| 48 | + |
| 49 | +In case you do not like the default font delivered with Zettlr, or need to change it, simply paste the following code snippet into the custom CSS editor. Replace `your-font-name` with the **full name** of the font you want to use for Zettlr. Please replace `placeholder` according to the font: |
| 50 | + |
| 51 | +- In case you want to use a **serif** font, such as Times New Roman, or Georgia, please use `serif` |
| 52 | +- In case your font is **sans serif**, such as Arial or Helvetica, please use `sans-serif` |
| 53 | +- In case you want to switch to the classic **monospace**, please use the placeholder `monospace` |
| 54 | + |
| 55 | +The placeholder will make sure that even if your font cannot be found, an equivalent font will be used. It serves as a fallback. Also, if your font name contains spaces, make sure to surround it with quotation marks, e.g., `"Times New Roman"`. |
| 56 | + |
| 57 | +```css |
| 58 | +body .main-editor-wrapper .cm-editor{ |
| 59 | + font-family: '<your-font-name here>', <placeholder>; |
| 60 | +} |
| 61 | +``` |
| 62 | +### Custom Background Images |
| 63 | + |
| 64 | +With the following code, you can make your editor have a different background image everytime you start it. The images are taken from Unsplash.com, a nice site with free photos. It uses the `Source API`, which will simply spit out a different image every time the URL is visited. You can test it out by simply [visiting the page and refreshing a few times](https://source.unsplash.com/random)! Please refer to the [Unsplash Source API reference](https://source.unsplash.com/) for more options (such as using an image of the day). |
| 65 | + |
| 66 | +!!! tip |
| 67 | + |
| 68 | + You can also use a local image as a background image by replacing the corresponding line by `background-image: url('file:////absolute/path/to/your/file.jpg');` |
| 69 | + |
| 70 | +```css |
| 71 | +/* Enter your custom CSS here */ |
| 72 | + |
| 73 | +.main-editor-wrapper .cm-editor{ |
| 74 | + background-color: transparent; |
| 75 | + background-image: url('https://source.unsplash.com/random'); |
| 76 | + background-size: cover; |
| 77 | + background-position: center center; |
| 78 | +} |
| 79 | + |
| 80 | +body .main-editor-wrapper .cm-editor .cm-content{ |
| 81 | + background-color: rgba(255, 255, 255, .8); |
| 82 | +} |
| 83 | +body .main-editor-wrapper .cm-editor{ |
| 84 | + background-color: rgba(255, 255, 255, .8); |
| 85 | +} |
| 86 | +body.dark .main-editor-wrapper .cm-editor .cm-content{ |
| 87 | + background-color: rgba(0, 0, 0, .8); |
| 88 | +} |
| 89 | +``` |
| 90 | +*Light Mode* |
| 91 | + |
| 92 | + |
| 93 | +*Dark Mode* |
| 94 | + |
| 95 | + |
| 96 | +### Visualising Line Endings |
| 97 | + |
| 98 | +In case you want to see where your linefeeds are, you can display the pilcrow symbol (¶) at the end of your lines by using the following Custom CSS: |
| 99 | + |
| 100 | +```css |
| 101 | +.cm-line:not(:last-child)::after { |
| 102 | + content: "¶"; |
| 103 | + color: #666; |
| 104 | +} |
| 105 | +``` |
| 106 | + |
| 107 | + |
| 108 | + |
| 109 | +### Change the Active Line Styling in Typewriter Mode |
| 110 | + |
| 111 | +You can change the styling of the active line in Typewriter mode. Replace `top-border-hex-code`, `bottom-border-hex-code` and `background-hex-code` in the CSS snippets below with your preferred Hex colour codes, which you can choose from a website such as [HTML Color Codes](https://htmlcolorcodes.com/). You may want to have different colour styling for light and dark mode. |
| 112 | + |
| 113 | +*Light mode* |
| 114 | + |
| 115 | +```css |
| 116 | +body .main-editor-wrapper .cm-editor .cm-content .typewriter-active-line { |
| 117 | + border-top: 2px solid <top-border-hex-code>; |
| 118 | + border-bottom: 2px solid <bottom-border-hex-code>; |
| 119 | + background-color: <background-hex-code>; |
| 120 | +} |
| 121 | +``` |
| 122 | + |
| 123 | +*Dark mode* |
| 124 | + |
| 125 | +```css |
| 126 | +body.dark .main-editor-wrapper .cm-editor .cm-content .typewriter-active-line { |
| 127 | + border-top: 2px solid <top-border-hex-code>; |
| 128 | + border-bottom: 2px solid <bottom-border-hex-code>; |
| 129 | + background-color: <background-hex-code>; |
| 130 | +} |
| 131 | +``` |
| 132 | + |
| 133 | +!!! warning |
| 134 | + |
| 135 | + The example CSS Code Snippets above have been updated and tested with v3.0.1 and so should work with newer versions of Zettlr, but the ones below haven't been updated in some time, and are unlikely to work out of the box. |
| 136 | + |
| 137 | + |
| 138 | +### Set a maximum width for the text |
| 139 | + |
| 140 | +If you have a large screen, you may find that lines of your text are very long. |
| 141 | +If you wish to have shorter lines in the editor, with margins on both sides, you can use the following CSS snippet: |
| 142 | + |
| 143 | +```css |
| 144 | +#editor { |
| 145 | + --side-margin: calc( 50vw - 30em ); |
| 146 | +} |
| 147 | + |
| 148 | +#editor .CodeMirror { |
| 149 | + margin-left: var(--side-margin); |
| 150 | +} |
| 151 | + |
| 152 | +#editor .CodeMirror-scroll { |
| 153 | + padding-right: var(--side-margin); |
| 154 | +} |
| 155 | +``` |
| 156 | + |
| 157 | + |
| 158 | + |
| 159 | +For the distraction free mode, the CSS snippet needs to be modified as follows: |
| 160 | + |
| 161 | +```css |
| 162 | +#editor.fullscreen { |
| 163 | + --side-margin-fullscreen: calc( 50vw - 30em ); |
| 164 | +} |
| 165 | + |
| 166 | +#editor.fullscreen .CodeMirror-fullscreen { |
| 167 | + margin-left: var(--side-margin-fullscreen) !important; |
| 168 | +} |
| 169 | + |
| 170 | +#editor.fullscreen .CodeMirror-fullscreen .CodeMirror-scroll { |
| 171 | + padding-right: var(--side-margin-fullscreen) !important; |
| 172 | +} |
| 173 | +``` |
| 174 | + |
| 175 | +By adjusting the calc functions for the two different modes, the same line width can be achieved with and without the file manager/sidebar. |
0 commit comments