From eeb9fe97c26ff27de78683aa79c1cc62e253b284 Mon Sep 17 00:00:00 2001 From: Yohan Boniface Date: Sat, 16 Jun 2018 13:28:13 +0200 Subject: [PATCH] Basic documentation on how to customize uMap look&feel --- docs/custom.md | 83 ++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + umap/static/umap/umap.png | Bin 4304 -> 0 bytes 3 files changed, 84 insertions(+) create mode 100644 docs/custom.md delete mode 100644 umap/static/umap/umap.png diff --git a/docs/custom.md b/docs/custom.md new file mode 100644 index 00000000..9f9aab23 --- /dev/null +++ b/docs/custom.md @@ -0,0 +1,83 @@ +# Customize your uMap installation + + +When running your own uMap, you may want to changed its appearance, for example +you want your own logo on the home page, or you want to apply some design, or +you want to add some tracking (but anonymous!) script… + +This is done by overriding templates, CSS and images and telling uMap about +that. +So basically you'll have your own templates and/or statics directories where +you will put the templates or statics you want to control (and only those). + +Inside thore directory, you need to respect the exact relative path of the +templates or statics you are adding, relatively to the +[templates](https://github.com/umap-project/umap/tree/master/umap/templates) +and +[static](https://github.com/umap-project/umap/tree/master/umap/static) +roots in the uMap structure. +For example, if you want to control the logo, you will add your own static with +the relative path `umap/img/logo.svg`. + +The same apply to any file inside `umap/templates` and `umap/statics`. + +## Settings + +- `UMAP_CUSTOM_TEMPLATES` (`path`): points to the directory where the custom + templates are stored +- `UMAP_CUSTOM_STATICS` (`path`): points to the directory where the custom + templates are stored + + +## Example + +Let's say we want to customize the home page, with a custom header, a custom +logo, and some CSS adjustments. + +For this we need to control at least two files: + +- `umap/navigation.html` +- `umap/theme.css` + +Let's create one templates directory: + + mkdir -p /srv/umap/custom/templates/ + +And one static directory: + + mkdir -p /srv/umap/custom/static/ + +Now let's create our custom navigation file: + + vim /srv/umap/custom/templates/umap/navigation.html + +We certainly want to copy-paste the +[original one](https://github.com/umap-project/umap/blob/master/umap/templates/umap/navigation.html) +to adapt it. + +Now let's add our custom logo, with whatever path inside the static dir, given +we'll customize also the CSS: + + mv mylogo.png /srv/umap/custom/static/umap/mylogo.png + +And then let's add some custom rules, for example the one to load our logo: + +```css +.umap-nav h1 a { + background-image: url("./img/mylogo.png"); +} +``` + +And we want the header to be red: + +```css +.umap-nav { + background-color: red; +} +``` + +And so on! + +See also +[https://github.com/etalab/cartes.data.gouv.fr](https://github.com/etalab/cartes.data.gouv.fr) +for an example of customization. diff --git a/mkdocs.yml b/mkdocs.yml index 8f69ea69..aed0a972 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,4 +5,5 @@ pages: - Contributing: contributing.md - how-tos: - Ubuntu from scratch: ubuntu.md + - Customize your uMap style: custom.md theme: readthedocs diff --git a/umap/static/umap/umap.png b/umap/static/umap/umap.png deleted file mode 100644 index 7edbeff27939b8cef299a707a400eaafabd9b255..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 4304 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 yfiMAqFaZI9Fad!u0f8_9fiMAqFaeXop8)_G