BookStack Code Mirror - website/blob - content/docs/admin/visual-customisation.md

2 title = "Customising Visuals"

3 description = "Changing the colors, logo and styles of BookStack to suit your needs"

4 date = "2017-08-22"

5 type = "admin-doc"

8 You may want to customise BookStack to use custom branding, or you may just not like the default blue theme. Customising the branding of BookStack is super simple and can be done within the "Settings > Customization" area of the interface. Here you can change the application name, logo and the core colours used. Additional ways to customise are listed below:

9

10 {{<toc>}}

11

12 ### Changing Fonts

13

14 To change fonts you can make use of the "Custom HTML Head Content" customization setting by adding custom CSS to alter fonts used.

15 Copy the code below into this setting and alter the font names to your desired fonts:

16

17 ```html

18 <style>

19 body {

20 --font-body: 'Noto Serif', serif;

21 --font-heading: 'Roboto', sans-serif;

22 --font-code: 'Source Code Pro', monospace;

23 }

24 </style>

25 ```

26

27 Here's an example of using the 'Lato' font from [Google Web Fonts](https://fonts.google.com) as the main body text font:

28

29 ```html

30 <link href="https://fonts.googleapis.com/css?family=Lato" rel="stylesheet">

31 <style>

32 body {

33 --font-body: 'Lato', sans-serif;

34 }

35 </style>

36 ```

37

38 Some additional notes to consider when setting custom fonts:

39

40 - Changes won't apply to the main `/settings` pages of BookStack, since custom HTML head content is not applied here.

41 - If a heading font is not set via `--font-heading`, then the `--font-body` value will be used as a fallback.

42 - This system simply makes use of normal [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/var), and the values are used for the standard [CSS font-family](https://developer.mozilla.org/en-US/docs/Web/CSS/font-family) property.

43 - These fonts won't apply to PDF exports, where font availability and usage is more limited.

44 - The font used for `--font-code`, if set, should be a monospace font.

45

46 ### Changing Code Block Themes

47

48 When inserting code into a page, or when using the Markdown editor, the text you enter is highlighted by the [CodeMirror library](https://codemirror.net/).

49 For those that'd prefer a different colour scheme for code blocks, we do provide a custom `library-cm6::configure-theme` JavaScript event

50 which provides a couple of methods that allow registration of CodeMirror UI and syntax highlighting themes.

51

52 You can find more information, along with an example, in our [JavaScript public events documentation here](https://github.com/BookStackApp/BookStack/blob/development/dev/docs/javascript-public-events.md#library-cm6configure-theme).

53

54 ### Default Light/Dark Mode

55

56 By default, BookStack will be presented in "light mode". Users can toggle their light/dark mode preference

57 using one of the buttons either found on the homepage view, or within the header bar user dropdown menu.

58

59 If you'd instead like your instance to be presented in "dark mode" by default, you can add the following option to your `.env` file:

60

61 ```bash

62 # Use dark mode by default

63 # Will be overridden by any existing user/session preference.

64 APP_DEFAULT_DARK_MODE=true

65 ```

66

67 ### Default Book View

68

69 By default the `/books` page displays your books as a list. Users can change this option to list or grid view but if you'd like to set the default for public viewers or new users you can add the following to your `.env` file:

70

71 ```bash

72 # Show grid view by default

73 APP_VIEWS_BOOKS=grid

74

75 # Show list view by default

76 APP_VIEWS_BOOKS=list

77 ```

78

79 ### Further Customisation

80

81 If you need to customise BookStack further to the given controls in the settings area you can make use of the 'Custom HTML head content' setting. Using this you can add in any custom JavaScript or CSS content to override default BookStack functionality and styles.

82

83 [View the Hacking BookStack](/docs/admin/hacking-bookstack/) page for more advanced ways to achieve deeper customisation.