forked from protesilaos/modus-themes
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathmodus-themes.info
6336 lines (5051 loc) · 265 KB
/
modus-themes.info
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
This is modus-themes.info, produced by makeinfo version 7.0.3 from
modus-themes.texi.
Copyright (C) 2020-2023 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.3 or any later version published by the Free Software
Foundation; with no Invariant Sections, with the Front-Cover Texts
being “A GNU Manual,” and with the Back-Cover Texts as in (a)
below. A copy of the license is included in the section entitled
“GNU Free Documentation License.”
(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and
modify this GNU manual.”
INFO-DIR-SECTION Emacs misc features
START-INFO-DIR-ENTRY
* Modus Themes: (modus-themes). Elegant, highly legible and customizable themes.
END-INFO-DIR-ENTRY
File: modus-themes.info, Node: Top, Next: Overview, Up: (dir)
Modus themes for GNU Emacs
**************************
Copyright (C) 2020-2023 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.3 or any later version published by the Free Software
Foundation; with no Invariant Sections, with the Front-Cover Texts
being “A GNU Manual,” and with the Back-Cover Texts as in (a)
below. A copy of the license is included in the section entitled
“GNU Free Documentation License.”
(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and
modify this GNU manual.”
This manual, written by Protesilaos Stavrou, describes the
customization options for the Modus themes, and provides every other
piece of information pertinent to them.
The documentation furnished herein corresponds to stable version
4.3.0, released on 2023-09-19. Any reference to a newer feature which
does not yet form part of the latest tagged commit, is explicitly marked
as such.
Current development target is 4.4.0-dev.
• Package name (GNU ELPA): ‘modus-themes’
• Official manual: <https://protesilaos.com/emacs/modus-themes>
• Change log: <https://protesilaos.com/emacs/modus-themes-changelog>
• Color palette: <https://protesilaos.com/emacs/modus-themes-colors>
• Sample pictures:
<https://protesilaos.com/emacs/modus-themes-pictures>
• Git repo on SourceHut:
<https://git.sr.ht/~protesilaos/modus-themes>
• Mirrors:
• GitHub: <https://github.com/protesilaos/modus-themes>
• GitLab: <https://gitlab.com/protesilaos/modus-themes>
• Mailing list: <https://lists.sr.ht/~protesilaos/modus-themes>
• Backronym: My Old Display Unexpectedly Sharpened ... themes
* Menu:
* Overview::
* Installation::
* Enable and load::
* Customization options::
* Advanced customization::
* Face coverage::
* Notes on individual packages::
* Frequently Asked Questions::
* Contributing::
* Acknowledgements::
* GNU Free Documentation License::
* Indices::
— The Detailed Node Listing —
Overview
* How do the themes look like::
* Learn about the latest changes::
Installation
* Install manually from source::
* Install from the archives::
* Install on GNU/Linux::
* Dealing with byte compilation errors::
Install on GNU/Linux
* Debian 11 Bullseye::
* GNU Guix::
Enable and load
* The require-theme for built-in Emacs themes::
* Sample configuration with and without use-package::
* Differences between loading and enabling::
Customization options
* Custom reload theme:: Toggle auto-reload of the theme when setting custom variables
* Disable other themes:: Determine whether loading a Modus themes disables all others
* Bold constructs:: Toggle bold constructs in code
* Italic constructs:: Toggle italic font constructs in code
* Option for which themes to toggle::
* Mixed fonts:: Toggle mixing of font families
* Command prompts:: Control the style of command prompts
* Completion UIs:: Choose among several styles for completion UIs
* Org mode blocks:: Choose among plain, gray, or tinted backgrounds
* Heading styles:: Choose among several styles, also per heading level
* UI typeface:: Toggle the use of variable-pitch across the User Interface
* Palette overrides:: Refashion color values and/or semantic color mappings
Advanced customization
* Palette override presets::
* Stylistic variants using palette overrides::
* More accurate colors in terminal emulators::
* Range of color with terminal emulators::
* Preview theme colors::
* Per-theme customization settings::
* Get a single color from the palette::
* Use theme colors in code with modus-themes-with-colors::
* Do not extend the region background::
* Add padding to mode line::
* Remap face with local value::
* Font configurations for Org and others::
* Configure bold and italic faces::
* Custom Org todo keyword and priority faces::
* Custom Org emphasis faces::
* Update Org block delimiter fontification::
* Measure color contrast::
* Load theme depending on time of day::
* Backdrop for pdf-tools::
* Toggle themes without reloading them::
* A theme-agnostic hook for theme loading::
* Use more spacious margins or padding in Emacs frames::
* Custom hl-todo colors::
* Add support for solaire-mode::
Stylistic variants using palette overrides
* Make the mode line borderless::
* Make the active mode line colorful::
* Make the tab bar more or less colorful::
* Make the fringe invisible or another color::
* Make links use subtle or no underlines::
* Make prompts more or less colorful::
* Make completion matches more or less colorful::
* Make comments yellow and strings green::
* Make code syntax use the old alt-syntax style::
* Make use of alternative styles for code syntax::
* Make matching parenthesis more or less intense::
* Make box buttons more or less gray::
* Make TODO and DONE more or less intense::
* Make headings more or less colorful::
* Make Org agenda more or less colorful::
* Make inline code in prose use alternative styles::
* Make mail citations and headers more or less colorful::
* Make the region preserve text colors, plus other styles: Make the region preserve text colors plus other styles.
* Make mouse highlights more or less colorful::
* Make language underlines less colorful::
* Make line numbers use alternative styles::
* Make diffs use only a foreground::
* Make deuteranopia diffs red and blue instead of yellow and blue::
* Make the themes look like what the maintainer uses::
Face coverage
* Supported packages:: Full list of covered face groups
* Indirectly covered packages::
Notes on individual packages
* Note on calendar.el weekday and weekend colors: Note on calendarel weekday and weekend colors.
* Note on git-gutter in Doom Emacs::
* Note on php-mode multiline comments::
* Note on underlines in compilation buffers::
* Note on inline Latex in Org buffers::
* Note on dimmer.el: Note on dimmerel.
* Note on display-fill-column-indicator-mode::
* Note on highlight-parentheses.el: Note on highlight-parenthesesel.
* Note on mmm-mode.el background colors: Note on mmm-modeel background colors.
* Note for prism::
* Note on company-mode overlay pop-up::
* Note on ERC escaped color sequences::
* Note on powerline or spaceline::
* Note on SHR colors::
* Note on SHR fonts::
* Note on Ement colors and fonts::
* Note on pdf-tools link hints::
* Note on the Notmuch logo::
* Note on goto-address-mode faces::
Frequently Asked Questions
* Is the contrast ratio about adjacent colors?::
* What does it mean to avoid exaggerations?::
* Why are colors mostly variants of blue, magenta, cyan?: Why are colors mostly variants of blue magenta cyan?.
* What is the best setup for legibility?::
* Are these color schemes?::
* Port the Modus themes to other platforms?::
Contributing
* Sources of the themes::
* Issues you can help with::
* Patches require copyright assignment to the FSF::
Indices
* Function index::
* Variable index::
* Concept index::
File: modus-themes.info, Node: Overview, Next: Installation, Prev: Top, Up: Top
1 Overview
**********
The Modus themes are designed for accessible readability. They conform
with the highest standard for color contrast between combinations of
background and foreground values. For small sized text, this
corresponds to the WCAG AAA standard, which specifies a minimum rate of
distance in relative luminance of 7:1.
The Modus themes consist of eight themes, divided into four
subgroups.
Main themes
‘modus-operandi’ is the project’s main light theme, while
‘modus-vivendi’ is its dark counterpart. These two themes are part
of the project since its inception. They are designed to cover a
broad range of needs and are, in the opinion of the author, the
reference for what a highly legible “default” theme should look
like.
Tinted themes
‘modus-operandi-tinted’ and ‘modus-vivendi-tinted’ are variants of
the two main themes. They slightly tone down the intensity of the
background and provide a bit more color variety.
‘modus-operandi-tinted’ has a set of base tones that are shades of
light ochre (earthly colors), while ‘modus-vivendi-tinted’ gives a
night sky impression.
Deuteranopia themes
‘modus-operandi-deuteranopia’ and its companion
‘modus-vivendi-deuteranopia’ are optimized for users with red-green
color deficiency. This means that they do not use red and green
hues for color-coding purposes, such as for diff removed and added
lines. Instead, they implement colors that are discernible by
users with deueteranopia or deuteranomaly (mostly yellow and blue
hues).
Tritanopia themes
‘modus-operandi-tritanopia’ and its counterpart
‘modus-vivendi-tritanopia’ are optimized for users with blue-yellow
color deficiency. The idea is the same as with the deuteranopia
variants: color coding relies only on hues that are accessible to
people with tritanopia or tritanomaly, namely, shades of red and
cyan.
To ensure that users have a consistently accessible experience, the
themes strive to achieve as close to full face coverage as possible,
while still targeting a curated list of well-maintained packages (*note
Face coverage::).
The overarching objective of this project is to always offer
accessible color combinations. There shall never be a compromise on
this principle. If there arises an inescapable trade-off between
usability and stylistic considerations, we will always opt for the
former.
Starting with version 0.12.0 and onwards, the themes are built into
GNU Emacs.
* Menu:
* How do the themes look like::
* Learn about the latest changes::
File: modus-themes.info, Node: How do the themes look like, Next: Learn about the latest changes, Up: Overview
1.1 How do the themes look like
===============================
Check the web page with the screen shots
(https://protesilaos.com/emacs/modus-themes-pictures/). Note that the
themes are highly customizable (*note Customization options::).
File: modus-themes.info, Node: Learn about the latest changes, Prev: How do the themes look like, Up: Overview
1.2 Learn about the latest changes
==================================
Please refer to the web page with the change log
(https://protesilaos.com/emacs/modus-themes-changelog). It is
comprehensive and covers everything that goes into every tagged release
of the themes.
File: modus-themes.info, Node: Installation, Next: Enable and load, Prev: Overview, Up: Top
2 Installation
**************
The Modus themes are distributed with Emacs starting with version 28.1.
On older versions of Emacs, they can be installed using Emacs’ package
manager or manually from their code repository. There also exist
packages for distributions of GNU/Linux.
Emacs 28 ships with ‘modus-themes’ version ‘1.6.0’. Emacs 29
includes version ‘3.0.0’. Emacs 30 provides a newer, refactored version
that thoroughly refashions how the themes are implemented and
customized. Such major versions are not backward-compatible due to the
limited resources at the maintainer’s disposal to support multiple
versions of Emacs and of the themes across the years.
* Menu:
* Install manually from source::
* Install from the archives::
* Install on GNU/Linux::
* Dealing with byte compilation errors::
File: modus-themes.info, Node: Install manually from source, Next: Install from the archives, Up: Installation
2.1 Install manually from source
================================
In the following example, we are assuming that your Emacs files are
stored in ‘~/.emacs.d’ and that you want to place the Modus themes in
‘~/.emacs.d/modus-themes’.
1. Get the source and store it in the desired path by running the
following in the command line shell:
$ git clone https://gitlab.com/protesilaos/modus-themes.git ~/.emacs.d/modus-themes
1. Add that path to your known Elisp libraries’ list, by placing this
snippet of Emacs Lisp in your init file (e.g. ‘init.el’):
(add-to-list 'load-path "~/.emacs.d/modus-themes")
The themes are now ready to be used: *note Enable and load::.
File: modus-themes.info, Node: Install from the archives, Next: Install on GNU/Linux, Prev: Install manually from source, Up: Installation
2.2 Install from the archives
=============================
The ‘modus-themes’ package is available from the GNU ELPA archive, which
is configured by default.
Prior to querying any package archive, make sure to update the index,
with ‘M-x package-refresh-contents’. Then all you need to do is type
‘M-x package-install’ and specify the ‘modus-themes’.
Once installed, the themes are ready to be used: *note Enable and
load::.
File: modus-themes.info, Node: Install on GNU/Linux, Next: Dealing with byte compilation errors, Prev: Install from the archives, Up: Installation
2.3 Install on GNU/Linux
========================
The themes are also available from the archives of some distributions of
GNU/Linux. These should correspond to a tagged release rather than
building directly from the latest Git commit. It all depends on the
distro’s packaging policies.
* Menu:
* Debian 11 Bullseye::
* GNU Guix::
File: modus-themes.info, Node: Debian 11 Bullseye, Next: GNU Guix, Up: Install on GNU/Linux
2.3.1 Debian 11 Bullseye
------------------------
The themes are part of Debian 11 Bullseye. Get them with:
sudo apt install elpa-modus-themes
They are now ready to be used: *note Enable and load::.
NOTE that Debian’s package is severely out-of-date as of this writing
2022-07-24 09:57 +0300.
File: modus-themes.info, Node: GNU Guix, Prev: Debian 11 Bullseye, Up: Install on GNU/Linux
2.3.2 GNU Guix
--------------
Users of Guix can get the themes with this command:
guix package -i emacs-modus-themes
They are now ready to be used: *note Enable and load::.
File: modus-themes.info, Node: Dealing with byte compilation errors, Prev: Install on GNU/Linux, Up: Installation
2.4 Dealing with byte compilation errors
========================================
From time to time, we receive bug reports pertaining to errors with byte
compilation. These seldom have to do with faulty code in the themes: it
might be a shortcoming of ‘package.el’, some regression in the current
development target of Emacs, a misconfiguration in an otherwise exotic
setup, and the like.
The common solution with a stable version of Emacs is to:
1. Delete the ‘modus-themes’ package.
2. Close the current Emacs session.
3. Install the ‘modus-themes’ again.
For those building Emacs directly from source, the solution may
involve reverting to an earlier commit in emacs.git.
At any rate, if you encounter such an issue please report it: we will
either fix the bug on our end if it is truly ours, or help forward it to
the relevant upstream maintainer. Whatever you do, please understand
that a build failure does not mean we are necessarily doing something
wrong.
*note Issues you can help with::.
File: modus-themes.info, Node: Enable and load, Next: Customization options, Prev: Installation, Up: Top
3 Enable and load
*****************
NOTE that Emacs can load multiple themes, which typically produces
undesirable results and undoes the work of the designer. Use the
‘disable-theme’ command if you are trying other themes beside the Modus
collection (*note Option for disabling other themes while loading Modus:
Disable other themes.).
Users of the built-in themes cannot ‘require’ the package as usual
because there is no package to speak of. Instead, things are simpler as
built-in themes are considered safe. All one needs is to load the theme
of their preference by adding either form to their init file:
(load-theme 'modus-operandi) ; Light theme
(load-theme 'modus-vivendi) ; Dark theme
Remember that there are multiple Modus themes (*note Overview::).
Adapt the above snippet accordingly.
Users of packaged variants of the themes must add a few more lines to
ensure that everything works as intended. First, one has to require the
main library before loading one of the themes:
(require 'modus-themes)
One can activate a theme with something like the following
expression, replacing ‘modus-operandi’ with their preferred Modus theme:
(load-theme 'modus-operandi :no-confirm)
Changes to the available customization options must always be
evaluated before loading a theme (*note Customization Options:
Customization options.). Reload a theme for new changes to take effect.
This is how a basic setup could look like (*note The require-theme
for built-in Emacs themes: The require-theme for built-in Emacs
themes.):
;;; For the built-in themes which cannot use `require'.
(require-theme 'modus-themes)
;; Add all your customizations prior to loading the themes.
(setq modus-themes-italic-constructs t
modus-themes-bold-constructs nil)
;; Load the theme of your choice.
(load-theme 'modus-operandi)
;; Optionally define a key to switch between Modus themes. Also check
;; the user option `modus-themes-to-toggle'.
(define-key global-map (kbd "<f5>") #'modus-themes-toggle)
;;; For packaged versions which must use `require'.
(require 'modus-themes)
;; Add all your customizations prior to loading the themes
(setq modus-themes-italic-constructs t
modus-themes-bold-constructs nil)
;; Load the theme of your choice.
(load-theme 'modus-operandi :no-confirm)
(define-key global-map (kbd "<f5>") #'modus-themes-toggle)
*note Sample configuration with and without use-package::.
To disable other themes before loading a Modus theme, use something
like this:
(mapc #'disable-theme custom-enabled-themes)
(load-theme 'modus-operandi :no-confirm)
Instead of using the basic ‘load-theme’ function, users can rely on
the ‘modus-themes-load-theme’. It accepts a single argument, which is a
symbol representing the Modus theme of choice, such as:
(modus-themes-load-theme 'modus-operandi)
The ‘modus-themes-load-theme’ takes care to disable other themes, if
the user opts in (*note Option for disabling other themes while loading
Modus: Disable other themes.). After loading the theme of choice, this
function calls the hook ‘modus-themes-after-load-theme-hook’ (alias
‘modus-themes-post-load-hook’). Users can add their own functions to
this hook to make further customizations (*note Advanced
customization::).
The commands ‘modus-themes-toggle’ and ‘modus-themes-select’ use
‘modus-themes-load-theme’ internally (*note Option for which themes to
toggle::). The aforementioned hold true for them as well.
* Menu:
* The require-theme for built-in Emacs themes::
* Sample configuration with and without use-package::
* Differences between loading and enabling::
File: modus-themes.info, Node: The require-theme for built-in Emacs themes, Next: Sample configuration with and without use-package, Up: Enable and load
3.1 The ‘require-theme’ for built-in Emacs themes
=================================================
The version of the Modus themes that is included in Emacs CANNOT use the
standard ‘require’. This is because the built-in themes are not
included in the ‘load-path’ (not my decision). The ‘require-theme’
function must be used in this case as a replacement. For example:
(require-theme 'modus-themes)
;; All customizations here
(setq modus-themes-bold-constructs t
modus-themes-italic-constructs t)
;; Maybe define some palette overrides, such as by using our presets
(setq modus-themes-common-palette-overrides
modus-themes-preset-overrides-intense)
;; Load the theme of choice (built-in themes are always "safe" so they
;; do not need the `no-require' argument of `load-theme').
(load-theme 'modus-operandi)
(define-key global-map (kbd "<f5>") #'modus-themes-toggle)
File: modus-themes.info, Node: Sample configuration with and without use-package, Next: Differences between loading and enabling, Prev: The require-theme for built-in Emacs themes, Up: Enable and load
3.2 Sample configuration with and without use-package
=====================================================
What follows is a variant of what we demonstrate in the previous section
(*note Enable and load::).
It is common for Emacs users to rely on ‘use-package’ for declaring
package configurations in their setup. We use this as an example:
;;; For the built-in themes which cannot use `require'.
(use-package emacs
:config
(require-theme 'modus-themes) ; `require-theme' is ONLY for the built-in Modus themes
;; Add all your customizations prior to loading the themes
(setq modus-themes-italic-constructs t
modus-themes-bold-constructs nil)
;; Maybe define some palette overrides, such as by using our presets
(setq modus-themes-common-palette-overrides
modus-themes-preset-overrides-intense)
;; Load the theme of your choice.
(load-theme 'modus-operandi)
(define-key global-map (kbd "<f5>") #'modus-themes-toggle))
;;; For packaged versions which must use `require'.
(use-package modus-themes
:ensure t
:config
;; Add all your customizations prior to loading the themes
(setq modus-themes-italic-constructs t
modus-themes-bold-constructs nil)
;; Maybe define some palette overrides, such as by using our presets
(setq modus-themes-common-palette-overrides
modus-themes-preset-overrides-intense)
;; Load the theme of your choice.
(load-theme 'modus-operandi)
(define-key global-map (kbd "<f5>") #'modus-themes-toggle))
The same without ‘use-package’:
(require 'modus-themes) ; OR for the built-in themes: (require-theme 'modus-themes)
;; Add all your customizations prior to loading the themes
(setq modus-themes-italic-constructs t
modus-themes-bold-constructs nil)
;; Maybe define some palette overrides, such as by using our presets
(setq modus-themes-common-palette-overrides
modus-themes-preset-overrides-intense)
;; Load the theme of your choice:
(load-theme 'modus-operandi :no-confirm)
(define-key global-map (kbd "<f5>") #'modus-themes-toggle)
*note Differences between loading and enabling::.
Note: make sure not to customize the variable
‘custom-theme-load-path’ or ‘custom-theme-directory’ after the themes’
package declaration. That will lead to failures in loading the files.
If either or both of those variables need to be changed, their values
should be defined before the package declaration of the themes.
*note Make the themes look like what the maintainer uses::
File: modus-themes.info, Node: Differences between loading and enabling, Prev: Sample configuration with and without use-package, Up: Enable and load
3.3 Differences between loading and enabling
============================================
The reason we recommend ‘load-theme’ instead of the other option of
‘enable-theme’ is that the former does a kind of “reset” on the face
specs. It quite literally loads (or reloads) the theme. Whereas the
‘enable-theme’ function simply puts an already loaded theme to the top
of the list of enabled items, re-using whatever state was last loaded.
As such, ‘load-theme’ reads all customizations that may happen during
any given Emacs session: even after the initial setup of a theme.
Examples are calls to ‘custom-set-faces’, as well as new values assigned
to the options the Modus themes provide (*note Customization Options:
Customization options.).
Our tests show that ‘enable-theme’ does not read such variables anew,
so it might appear to the unsuspecting user that the themes are somehow
broken whenever they try to assign a new value to a customization option
or some face.
This “reset” that ‘load-theme’ brings about does, however, come at
the cost of being somewhat slower than ‘enable-theme’. Users who have a
stable setup and who seldom update their variables during a given Emacs
session, are better off using something like this:
(require 'modus-themes)
;; Activate your desired themes here
(load-theme 'modus-operandi t t)
(load-theme 'modus-vivendi t t)
;; Enable the preferred one
(enable-theme 'modus-operandi)
*note Toggle themes without reloading them::.
*note Sample configuration with and without use-package::.
With the above granted, other sections of the manual discuss how to
configure custom faces, where ‘load-theme’ is expected, though
‘enable-theme’ could still apply in stable setups:
*note Use theme colors in code with modus-themes-with-colors::.
File: modus-themes.info, Node: Customization options, Next: Advanced customization, Prev: Enable and load, Up: Top
4 Customization options
***********************
The Modus themes are highly configurable, though they should work well
without any further tweaks. We provide a variety of user options. The
following code block provides an overview. In addition to those
variables, the themes support a comprehensive system of overrides: it
can be used to make thoroughgoing changes to the looks of the themes
(*note Option for palette overrides: Palette overrides.). We document
everything at length in the pages of this manual and also provide
ready-to-use code samples.
Remember that all customization options must be evaluated before
loading a theme (*note Enable and load::). If the theme is already
active, it must be reloaded for changes to take effect.
;; In all of the following, WEIGHT is a symbol such as `semibold',
;; `light', `bold', or anything mentioned in `modus-themes-weights'.
(setq modus-themes-italic-constructs t
modus-themes-bold-constructs nil
modus-themes-mixed-fonts t
modus-themes-variable-pitch-ui nil
modus-themes-custom-auto-reload t
modus-themes-disable-other-themes t
;; Options for `modus-themes-prompts' are either nil (the
;; default), or a list of properties that may include any of those
;; symbols: `italic', `WEIGHT'
modus-themes-prompts '(italic bold)
;; The `modus-themes-completions' is an alist that reads two
;; keys: `matches', `selection'. Each accepts a nil value (or
;; empty list) or a list of properties that can include any of
;; the following (for WEIGHT read further below):
;;
;; `matches' :: `underline', `italic', `WEIGHT'
;; `selection' :: `underline', `italic', `WEIGHT'
modus-themes-completions
'((matches . (extrabold))
(selection . (semibold italic text-also)))
modus-themes-org-blocks 'gray-background ; {nil,'gray-background,'tinted-background}
;; The `modus-themes-headings' is an alist: read the manual's
;; node about it or its doc string. Basically, it supports
;; per-level configurations for the optional use of
;; `variable-pitch' typography, a height value as a multiple of
;; the base font size (e.g. 1.5), and a `WEIGHT'.
modus-themes-headings
'((1 . (variable-pitch 1.5))
(2 . (1.3))
(agenda-date . (1.3))
(agenda-structure . (variable-pitch light 1.8))
(t . (1.1))))
;; Remember that more (MUCH MORE) can be done with overrides, which we
;; document extensively in this manual.
* Menu:
* Custom reload theme:: Toggle auto-reload of the theme when setting custom variables
* Disable other themes:: Determine whether loading a Modus themes disables all others
* Bold constructs:: Toggle bold constructs in code
* Italic constructs:: Toggle italic font constructs in code
* Option for which themes to toggle::
* Mixed fonts:: Toggle mixing of font families
* Command prompts:: Control the style of command prompts
* Completion UIs:: Choose among several styles for completion UIs
* Org mode blocks:: Choose among plain, gray, or tinted backgrounds
* Heading styles:: Choose among several styles, also per heading level
* UI typeface:: Toggle the use of variable-pitch across the User Interface
* Palette overrides:: Refashion color values and/or semantic color mappings
File: modus-themes.info, Node: Custom reload theme, Next: Disable other themes, Up: Customization options
4.1 Option for reloading the theme on custom change
===================================================
Brief: Toggle reloading of the active theme when an option is changed
through the Custom UI.
Symbol: ‘modus-themes-custom-auto-reload’ (‘boolean’ type)
Possible values:
1. ‘nil’
2. ‘t’ (default)
All theme user options take effect when a theme is loaded. Any
subsequent changes require the theme to be reloaded.
When this variable has a non-‘nil’ value, any change made via the
Custom UI or related functions such as ‘customize-set-variable’ and
‘setopt’ (Emacs 29), will trigger a reload automatically.
With a ‘nil’ value, changes to user options have no further
consequences: the user must manually reload the theme (*note Enable and
load::).
File: modus-themes.info, Node: Disable other themes, Next: Bold constructs, Prev: Custom reload theme, Up: Customization options
4.2 Option for disabling other themes while loading Modus
=========================================================
Brief: Disable all other themes when loading a Modus theme.
Symbol: ‘modus-themes-disable-other-themes’ (‘boolean’ type)
Possible values:
1. ‘nil’
2. ‘t’ (default)
When the value is non-‘nil’, the commands ‘modus-themes-toggle’ and
‘modus-themes-select’, as well as the ‘modus-themes-load-theme’
function, will disable all other themes while loading the specified
Modus theme (*note Option for which themes to toggle::). This is done
to ensure that Emacs does not blend two or more themes: such blends lead
to awkward results that undermine the work of the designer.
When the value is ‘nil’, the aforementioned commands and function
will only disable other themes within the Modus collection.
This option is provided because Emacs themes are not necessarily
limited to colors/faces: they can consist of an arbitrary set of
customizations. Users who use such customization bundles must set this
variable to a ‘nil’ value.
File: modus-themes.info, Node: Bold constructs, Next: Italic constructs, Prev: Disable other themes, Up: Customization options
4.3 Option for more bold constructs
===================================
Brief: Use bold for code syntax highlighting and related.
Symbol: ‘modus-themes-bold-constructs’ (‘boolean’ type)
Possible values:
1. ‘nil’ (default)
2. ‘t’
The default is to use a bold typographic weight only when it is
required.
With a non-‘nil’ value (‘t’) display several syntactic constructs in
bold weight. This concerns keywords and other important aspects of code
syntax. It also affects certain mode line indicators and command
prompts.
Advanced users may also want to configure the exact attributes of the
‘bold’ face.
*note Configure bold and italic faces::.
File: modus-themes.info, Node: Italic constructs, Next: Option for which themes to toggle, Prev: Bold constructs, Up: Customization options
4.4 Option for more italic constructs
=====================================
Brief: Use italics for code syntax highlighting and related.
Symbol: ‘modus-themes-italic-constructs’ (‘boolean’ type)
Possible values:
1. ‘nil’ (default)
2. ‘t’
The default is to not use slanted text forms (italics) unless it is
absolutely necessary.
With a non-‘nil’ value (‘t’) choose to render more faces in italics.
This typically affects documentation strings and code comments.
Advanced users may also want to configure the exact attributes of the
‘italic’ face.
*note Configure bold and italic faces::.
File: modus-themes.info, Node: Option for which themes to toggle, Next: Mixed fonts, Prev: Italic constructs, Up: Customization options
4.5 Option for which themes to toggle
=====================================
Brief: Choose to Modus themes to toggle between
Symbol: ‘modus-themes-to-toggle’ (‘list’ type)
Default value: ‘'(modus-operandi modus-vivendi)’
Possible values:
• ‘modus-operandi’
• ‘modus-vivendi’
• ‘modus-operandi-tinted’
• ‘modus-vivendi-tinted’
• ‘modus-operandi-deuteranopia’
• ‘modus-vivendi-deuteranopia’
• ‘modus-operandi-tritanopia’
• ‘modus-vivendi-tritanopia’
Specify two themes to toggle between using the command
‘modus-themes-toggle’.
File: modus-themes.info, Node: Mixed fonts, Next: Command prompts, Prev: Option for which themes to toggle, Up: Customization options
4.6 Option for font mixing
==========================
Brief: Toggle the use of monospaced fonts for spacing-sensitive
constructs (affects font families).
Symbol: ‘modus-themes-mixed-fonts’ (‘boolean’ type)
Possible values:
1. ‘nil’ (default)
2. ‘t’
When set to non-‘nil’ (‘t’), configure some spacing-sensitive faces
like Org tables and code blocks to always inherit from the ‘fixed-pitch’
face. This is to ensure that certain constructs like code blocks and
tables remain monospaced even when users opt for a mode that remaps
typeface families, such as the built-in ‘M-x variable-pitch-mode’.
Otherwise the layout can appear broken, due to how spacing is done.
For a consistent experience, user may need to specify the font family
of the ‘fixed-pitch’ face.
*note Font configurations for Org and others::.
File: modus-themes.info, Node: Command prompts, Next: Completion UIs, Prev: Mixed fonts, Up: Customization options
4.7 Option for command prompt styles
====================================
Brief: Control the style of command prompts (e.g. minibuffer, shell,
IRC clients).
Symbol: ‘modus-themes-prompts’ (‘choice’ type, list of properties)
Possible values are expressed as a list of properties (default is
‘nil’ or an empty list). The list can include any of the following
symbols:
• ‘italic’
• ‘italic’
• A font weight, which must be supported by the underlying typeface:
• ‘thin’
• ‘ultralight’
• ‘extralight’
• ‘light’
• ‘semilight’
• ‘regular’
• ‘medium’
• ‘semibold’
• ‘bold’
• ‘heavy’
• ‘extrabold’
• ‘ultrabold’
The default (a ‘nil’ value or an empty list) means to only use a
subtle colored foreground color.
The ‘italic’ property adds a slant to the font’s forms (italic or
oblique forms, depending on the typeface).
The symbol of a font weight attribute such as ‘light’, ‘semibold’, et
cetera, adds the given weight to links. Valid symbols are defined in
the variable ‘modus-themes-weights’. The absence of a weight means that
the one of the underlying text will be used.
Combinations of any of those properties are expressed as a list, like
in these examples:
(bold italic)
(italic semibold)
The order in which the properties are set is not significant.
In user configuration files the form may look like this:
(setq modus-themes-prompts '(extrabold italic))
*note Make prompts more or less colorful::.
File: modus-themes.info, Node: Completion UIs, Next: Org mode blocks, Prev: Command prompts, Up: Customization options
4.8 Option for completion framework aesthetics