Mercurial > kallithea
annotate docs/usage/customization.rst @ 8856:8014ac73587d
mail: drop unicode filter from templates
Unicode is the default in py3, and we no longer pass any non-string arguments
that need stringification before rendering.
This is backing out a part of 4fbab9d5be4d.
author | Mads Kiilerich <mads@kiilerich.com> |
---|---|
date | Tue, 16 Feb 2021 21:38:09 +0100 |
parents | e3d8f4bc3ce7 |
children |
rev | line source |
---|---|
5779
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
1 .. _customization: |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
2 |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
3 ============= |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
4 Customization |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
5 ============= |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
6 |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
7 There are several ways to customize Kallithea to your needs depending on what |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
8 you want to achieve. |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
9 |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
10 |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
11 HTML/JavaScript/CSS customization |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
12 --------------------------------- |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
13 |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
14 To customize the look-and-feel of the web interface (for example to add a |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
15 company banner or some JavaScript widget or to tweak the CSS style definitions) |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
16 you can enter HTML code (possibly with JavaScript and/or CSS) directly via the |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
17 *Admin > Settings > Global > HTML/JavaScript customization |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
18 block*. |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
19 |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
20 |
7244
8152f9e6a778
less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents:
6554
diff
changeset
|
21 Style sheet customization with Less |
8152f9e6a778
less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents:
6554
diff
changeset
|
22 ----------------------------------- |
8152f9e6a778
less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents:
6554
diff
changeset
|
23 |
8152f9e6a778
less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents:
6554
diff
changeset
|
24 Kallithea uses `Bootstrap 3`_ and Less_ for its style definitions. If you want |
8152f9e6a778
less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents:
6554
diff
changeset
|
25 to make some customizations, we recommend to do so by creating a ``theme.less`` |
7845
3b54bcf6d128
front-end: fix documentation regarding theme.less file
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents:
7437
diff
changeset
|
26 file. When you create a file named ``theme.less`` in directory |
3b54bcf6d128
front-end: fix documentation regarding theme.less file
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents:
7437
diff
changeset
|
27 ``kallithea/front-end/`` inside the Kallithea installation, you can use this |
3b54bcf6d128
front-end: fix documentation regarding theme.less file
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents:
7437
diff
changeset
|
28 file to override the default style. For example, you can use this to override |
3b54bcf6d128
front-end: fix documentation regarding theme.less file
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents:
7437
diff
changeset
|
29 ``@kallithea-theme-main-color``, ``@kallithea-logo-url`` or other `Bootstrap |
3b54bcf6d128
front-end: fix documentation regarding theme.less file
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents:
7437
diff
changeset
|
30 variables`_. |
7244
8152f9e6a778
less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents:
6554
diff
changeset
|
31 |
7437
b66725ba01ed
cli: add command 'kallithea-cli front-end-build'
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents:
7415
diff
changeset
|
32 After creating the ``theme.less`` file, you need to regenerate the CSS files, by |
b66725ba01ed
cli: add command 'kallithea-cli front-end-build'
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents:
7415
diff
changeset
|
33 running:: |
7244
8152f9e6a778
less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents:
6554
diff
changeset
|
34 |
7437
b66725ba01ed
cli: add command 'kallithea-cli front-end-build'
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents:
7415
diff
changeset
|
35 kallithea-cli front-end-build --no-install-deps |
7244
8152f9e6a778
less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents:
6554
diff
changeset
|
36 |
8152f9e6a778
less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents:
6554
diff
changeset
|
37 .. _bootstrap 3: https://getbootstrap.com/docs/3.3/ |
8152f9e6a778
less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents:
6554
diff
changeset
|
38 .. _bootstrap variables: https://getbootstrap.com/docs/3.3/customize/#less-variables |
8152f9e6a778
less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents:
6554
diff
changeset
|
39 .. _less: http://lesscss.org/ |
8152f9e6a778
less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents:
6554
diff
changeset
|
40 |
8152f9e6a778
less: load optional theme.less file to allow custom styles
domruf <dominikruf@gmail.com>
parents:
6554
diff
changeset
|
41 |
8655
e3d8f4bc3ce7
extensions: rename 'rcextensions' into 'extensions' but provide compatibility
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents:
7845
diff
changeset
|
42 Behavioral customization: Kallithea extensions |
e3d8f4bc3ce7
extensions: rename 'rcextensions' into 'extensions' but provide compatibility
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents:
7845
diff
changeset
|
43 ---------------------------------------------- |
5779
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
44 |
8655
e3d8f4bc3ce7
extensions: rename 'rcextensions' into 'extensions' but provide compatibility
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents:
7845
diff
changeset
|
45 Some behavioral customization can be done in Python using Kallithea |
e3d8f4bc3ce7
extensions: rename 'rcextensions' into 'extensions' but provide compatibility
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents:
7845
diff
changeset
|
46 ``extensions``, a custom Python file you can create to extend Kallithea |
e3d8f4bc3ce7
extensions: rename 'rcextensions' into 'extensions' but provide compatibility
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents:
7845
diff
changeset
|
47 functionality. |
5779
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
48 |
8655
e3d8f4bc3ce7
extensions: rename 'rcextensions' into 'extensions' but provide compatibility
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents:
7845
diff
changeset
|
49 With ``extensions`` it's possible to add additional mappings for Whoosh |
5779
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
50 indexing and statistics, to add additional code into the push/pull/create/delete |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
51 repository hooks (for example to send signals to build bots such as Jenkins) and |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
52 even to monkey-patch certain parts of the Kallithea source code (for example |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
53 overwrite an entire function, change a global variable, ...). |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
54 |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
55 To generate a skeleton extensions package, run:: |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
56 |
7415
f9c8fec48185
cli: convert 'gearbox make-rcext' in 'kallithea-cli extensions-create'
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents:
7244
diff
changeset
|
57 kallithea-cli extensions-create -c my.ini |
5779
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
58 |
8655
e3d8f4bc3ce7
extensions: rename 'rcextensions' into 'extensions' but provide compatibility
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents:
7845
diff
changeset
|
59 This will create an ``extensions.py`` file next to the specified ``ini`` file. |
e3d8f4bc3ce7
extensions: rename 'rcextensions' into 'extensions' but provide compatibility
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents:
7845
diff
changeset
|
60 You can find more details inside this file. |
e3d8f4bc3ce7
extensions: rename 'rcextensions' into 'extensions' but provide compatibility
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents:
7845
diff
changeset
|
61 |
e3d8f4bc3ce7
extensions: rename 'rcextensions' into 'extensions' but provide compatibility
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents:
7845
diff
changeset
|
62 For compatibility with previous releases of Kallithea, a directory named |
e3d8f4bc3ce7
extensions: rename 'rcextensions' into 'extensions' but provide compatibility
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents:
7845
diff
changeset
|
63 ``rcextensions`` with a file ``__init__.py`` inside of it can also be used. If |
e3d8f4bc3ce7
extensions: rename 'rcextensions' into 'extensions' but provide compatibility
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents:
7845
diff
changeset
|
64 both an ``extensions.py`` file and an ``rcextensions`` directory are found, only |
e3d8f4bc3ce7
extensions: rename 'rcextensions' into 'extensions' but provide compatibility
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents:
7845
diff
changeset
|
65 ``extensions.py`` will be loaded. Note that the name ``rcextensions`` is |
e3d8f4bc3ce7
extensions: rename 'rcextensions' into 'extensions' but provide compatibility
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents:
7845
diff
changeset
|
66 deprecated and support for it will be removed in a future release. |
5779
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
67 |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
68 |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
69 Behavioral customization: code changes |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
70 -------------------------------------- |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
71 |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
72 As Kallithea is open-source software, you can make any changes you like directly |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
73 in the source code. |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
74 |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
75 We encourage you to send generic improvements back to the |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
76 community so that Kallithea can become better. See :ref:`contributing` for more |
60f9840c8df1
docs: document Kallithea customization options
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
77 details. |