From 3ffa8975d4d826322fc8c54ac66a39ee25cc484f Mon Sep 17 00:00:00 2001 From: hagen1778 Date: Mon, 20 Nov 2023 11:52:09 +0100 Subject: [PATCH] docs: follow-up after d3f919df3eb172a7779b94efb442402215fd0581 https://github.com/VictoriaMetrics/VictoriaMetrics/commit/d3f919df3eb172a7779b94efb442402215fd0581 Signed-off-by: hagen1778 --- README.md | 35 +++++++++++++++------------ docs/Makefile | 9 +++---- docs/README.md | 19 +++++++++++++++ docs/Single-server-VictoriaMetrics.md | 19 +++++++++++++++ 4 files changed, 61 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 7f0c652bb..d96134d75 100644 --- a/README.md +++ b/README.md @@ -2494,6 +2494,25 @@ Adhering `KISS` principle simplifies the resulting code and architecture, so it Report bugs and propose new features [here](https://github.com/VictoriaMetrics/VictoriaMetrics/issues). +## Images in documentation + +Please, keep image size and number of images per single page low. Keep the docs page as lightweight as possible. + +If the page needs to have many images, consider using WEB-optimized image format [webp](https://developers.google.com/speed/webp). +When adding a new doc with many images use `webp` format right away. Or use a MAKEFILE command below to +convert already existing images automatically: +```console +PATH_TO_IMAGES=path/to/images IMAGES_EXTENSION={png|jpg|jpeg} IMAGE_QUALITY=0..100 make docs-images-to-webp +``` + +_// For this command to work ensure you run it when in `docs` dir (`cd docs`) and have Docker up&running._ + +Once conversion is done, update the path to images in your docs and verify everything is correct. +When you're happy with result - remove the originals with the following command: +```console +PATH_TO_IMAGES=path/to/images IMAGES_EXTENSION={png|jpg|jpeg} make docs-remove-old-images +``` + ## VictoriaMetrics Logo [Zip](https://github.com/VictoriaMetrics/VictoriaMetrics/blob/master/VM_logo.zip) contains three folders with different image orientations (main color and inverted version). @@ -2524,22 +2543,6 @@ Files included in each folder: * Do not change the proportions for any of the design elements or the design itself. You may resize as needed but must retain all proportions. -### Images in documentation - -* Images should have `.webp` format - -When documentation in the `docs` folder updated and some content should have images -those images can be added in format `.png`, `jpeg` or `jpg`. - -When content is finished and it is ready to be pushed to the repository all images should be converted -to the `.webp` format via -`PATH_TO_IMAGES=path/to/images IMAGES_EXTENSION=image_extension IMAGE_QUALITY=image_quality make docs-change-images` - -All images quality set to `IMAGE_QUALITY` but it just reduce the size of image, but not the display quality -This command will reduce all images with extionsion and folder defined in the command. -All images with defined extensions will be removed. -After that it is nesessary to update src attribute for image tag - ## List of command-line flags Pass `-help` to VictoriaMetrics in order to see the list of supported command-line flags with their description: diff --git a/docs/Makefile b/docs/Makefile index 6c7f3ec79..6992f3292 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -2,7 +2,7 @@ docs-install: gem install jekyll bundler bundle install --gemfile=Gemfile -# To run localy you need to use ruby version =< 2.7.6, but not >=3.x , see https://bbs.archlinux.org/viewtopic.php?pid=1976408#p1976408 +# To run locally you need to use ruby version =< 2.7.6, but not >=3.x , see https://bbs.archlinux.org/viewtopic.php?pid=1976408#p1976408 # # run local server for documentation website # at http://127.0.0.1:4000/ @@ -21,6 +21,9 @@ docs-up-docker: -v $(PWD):/srv/jekyll \ jekyll/jekyll:3.8 jekyll serve --livereload +# Converts $IMAGES_EXTENSION in the specified $PATH_TO_IMAGES +# to webp format with $IMAGE_QUALITY (0:small..100:big) +# See https://docs.victoriametrics.com/Single-server-VictoriaMetrics.html#images-in-documentation docs-images-to-webp: docker run -it --rm -v \ $(PWD)/$(PATH_TO_IMAGES):/data \ @@ -29,7 +32,3 @@ docs-images-to-webp: docs-remove-old-images: rm -f $(PWD)/$(PATH_TO_IMAGES)/*.$(IMAGES_EXTENSION) - -docs-change-images: \ - docs-images-to-webp \ - docs-remove-old-images diff --git a/docs/README.md b/docs/README.md index c7bb6ee67..8efae360a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2497,6 +2497,25 @@ Adhering `KISS` principle simplifies the resulting code and architecture, so it Report bugs and propose new features [here](https://github.com/VictoriaMetrics/VictoriaMetrics/issues). +## Images in documentation + +Please, keep image size and number of images per single page low. Keep the docs page as lightweight as possible. + +If the page needs to have many images, consider using WEB-optimized image format [webp](https://developers.google.com/speed/webp). +When adding a new doc with many images use `webp` format right away. Or use a MAKEFILE command below to +convert already existing images automatically: +```console +PATH_TO_IMAGES=path/to/images IMAGES_EXTENSION={png|jpg|jpeg} IMAGE_QUALITY=0..100 make docs-images-to-webp +``` + +_// For this command to work ensure you run it when in `docs` dir (`cd docs`) and have Docker up&running._ + +Once conversion is done, update the path to images in your docs and verify everything is correct. +When you're happy with result - remove the originals with the following command: +```console +PATH_TO_IMAGES=path/to/images IMAGES_EXTENSION={png|jpg|jpeg} make docs-remove-old-images +``` + ## VictoriaMetrics Logo [Zip](https://github.com/VictoriaMetrics/VictoriaMetrics/blob/master/VM_logo.zip) contains three folders with different image orientations (main color and inverted version). diff --git a/docs/Single-server-VictoriaMetrics.md b/docs/Single-server-VictoriaMetrics.md index 97ec5ff6d..80289300f 100644 --- a/docs/Single-server-VictoriaMetrics.md +++ b/docs/Single-server-VictoriaMetrics.md @@ -2505,6 +2505,25 @@ Adhering `KISS` principle simplifies the resulting code and architecture, so it Report bugs and propose new features [here](https://github.com/VictoriaMetrics/VictoriaMetrics/issues). +## Images in documentation + +Please, keep image size and number of images per single page low. Keep the docs page as lightweight as possible. + +If the page needs to have many images, consider using WEB-optimized image format [webp](https://developers.google.com/speed/webp). +When adding a new doc with many images use `webp` format right away. Or use a MAKEFILE command below to +convert already existing images automatically: +```console +PATH_TO_IMAGES=path/to/images IMAGES_EXTENSION={png|jpg|jpeg} IMAGE_QUALITY=0..100 make docs-images-to-webp +``` + +_// For this command to work ensure you run it when in `docs` dir (`cd docs`) and have Docker up&running._ + +Once conversion is done, update the path to images in your docs and verify everything is correct. +When you're happy with result - remove the originals with the following command: +```console +PATH_TO_IMAGES=path/to/images IMAGES_EXTENSION={png|jpg|jpeg} make docs-remove-old-images +``` + ## VictoriaMetrics Logo [Zip](https://github.com/VictoriaMetrics/VictoriaMetrics/blob/master/VM_logo.zip) contains three folders with different image orientations (main color and inverted version).