Image zoom and alt text (#275)

* add medium-zoom
* fix openssl error
* add docs how to create images

Author: PeterPetrik

.github/workflows/checks.yml

@@ -5,14 +5,19 @@ on: push
 jobs:
   spellcheck:
     runs-on: ubuntu-latest
-    
     steps:
     - uses: actions/checkout@v3
+
+    # need Node 16 or less to get rid of ERR_OSSL_EVP_UNSUPPORTED
+    - uses: actions/setup-node@v3
+      with:
+        node-version: 16
+
     - name: Generate dist
       run: |
         yarn install
         yarn build
-        
+
     - name: "Check dist dir consistency"
       uses: andstor/file-existence-action@v1
       with:
@@ -26,9 +31,14 @@ jobs:
 
   broken_links:
     runs-on: ubuntu-latest
-    
     steps:
     - uses: actions/checkout@v3
+
+    # need Node 16 or less to get rid of ERR_OSSL_EVP_UNSUPPORTED
+    - uses: actions/setup-node@v3
+      with:
+        node-version: 16
+
     - name: Generate dist
       run: |
         yarn install

.github/workflows/dist-dev.yml

@@ -17,13 +17,21 @@ jobs:
   deploy_dev:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
+
+    # need Node 16 or less to get rid of ERR_OSSL_EVP_UNSUPPORTED
+    - uses: actions/setup-node@v3
+      with:
+        node-version: 16
+
     - name: Install
       run: |
        yarn install
+
     - name: Generate dist
       run: |
         yarn build
+
     - name: "Check dist dir consistency"
       uses: andstor/file-existence-action@v1
       with:

.github/workflows/dist-prod.yml

@@ -14,19 +14,27 @@ jobs:
   deploy_prod:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
+
+    # need Node 16 or less to get rid of ERR_OSSL_EVP_UNSUPPORTED
+    - uses: actions/setup-node@v3
+      with:
+        node-version: 16
+
     - name: Install
       run: |
        yarn install
+
     - name: Generate dist
       run: |
         yarn build
+
     - name: "Check dist dir consistency"
       uses: andstor/file-existence-action@v1
       with:
         files: "dist/docs/index.html"
         allow_failure: true # Makes the Action fail on missing files
-        
+
     - name: Configure AWS credentials
       uses: aws-actions/configure-aws-credentials@v1
       with:

README.md

@@ -42,12 +42,7 @@ cd merginmaps/docs
 yarn install
 yarn dev
 ```
-
-If you get `  opensslErrorStack: [ 'error:03000086:digital envelope routines::initialization error' ]`, run
-```bash
-export NODE_OPTIONS=--openssl-legacy-provider
-```
-
+ 
 ## Static generation (for deployments)
 
 To generate static HTML files, run 
@@ -60,6 +55,20 @@ yarn build
 
 and see the result in `dist` folder
 
+### Error for nodejs 17
+
+If you get `opensslErrorStack: [ 'error:03000086:digital envelope routines::initialization error' ]`, run
+ ```bash
+ export NODE_OPTIONS=--openssl-legacy-provider
+ ```
+ 
+ or on Windows
+ ```bash
+ set NODE_OPTIONS=--openssl-legacy-provider
+ ```
+  
+ or downgrade `nodejs` to 16 or less. More here: https://github.com/webpack/webpack/issues/14532
+
 # License
 
 The Mergin Maps product documentation in the `src` are licensed under a [CC-BY license](LICENSE).

package.json

@@ -14,8 +14,9 @@
     "build": "vuepress build src",
     "export": "vuepress export src"
   },
-  "devDependencies": {
-    "vuepress": "^1.9.7",
+  "devDependencies": {  
+    "@vuepress/plugin-medium-zoom": "^1.9.8",
+    "vuepress": "^1.9.8",
     "vuepress-plugin-clean-urls": "^1.1.2",
     "vuepress-plugin-fulltext-search": "^2.2.1",
     "vuepress-plugin-google-tag-manager": "0.0.5"

scripts/wordlist.txt

@@ -185,6 +185,7 @@ prepopulated
 programmatically
 proj
 px
+kb
 qca
 qgs
 qgz

src/.vuepress/components/PublicImage.vue

@@ -1,12 +1,14 @@
 <template>
-  <img :src="$withBase(`/${src}`)">
+  <img :src="$withBase(`/${src}`)" :title="`${title}`" :alt="`${alt}`">
 </template>
 
 <script>
 export default {
   name: "publicimage",
   props: {
-    src: String
+    src: String,
+    title: String,
+    alt: String
   }
 }
 </script>

src/.vuepress/config.js

@@ -3,6 +3,14 @@ var path = require('path')
 const pageSuffix = '/'
 
 module.exports = {
+  /**
+   * fix ERR_OSSL_EVP_UNSUPPORTED for webpack4
+   * https://stackoverflow.com/a/73027407/2838364
+   */
+   configureWebpack: {
+     output: {hashFunction: 'sha256'}
+   },
+
   /**
    * Ref：https://v1.vuepress.vuejs.org/config/#title
    */
@@ -72,6 +80,7 @@ module.exports = {
     ['vuepress-plugin-google-tag-manager', {
       'gtm': 'GTM-NW7ZGNB'
     }],
+    ['@vuepress/medium-zoom'],
     [ 'clean-urls', {
       normalSuffix: pageSuffix,
       indexSuffix: pageSuffix

src/misc/troubleshoot.md

@@ -18,7 +18,7 @@ Need more help with your issue? <LutraConsultingWeb /> provides commercial suppo
 
 The commercial support or consultancy for your projects is carried by <LutraConsultingWeb />
 
-<PublicImage src="logo_lutra.svg" />
+<PublicImage src="logo_lutra.svg" title="Lutra Consulting Ltd. logo" />
 
 Please see the <LutraConsultingWeb id="support/" desc="support packages" /> available. SLA support offers you the contracted response time, dedicated hotline as well as premium email support.
 

src/misc/write-docs/index.md

@@ -282,22 +282,40 @@ You can use any of supported <GitHubRepo id="markdown-it/markdown-it-emoji/blob/
 	* Stroke the selection with red, at width:
 		* Desktop: 3px
 		* Mobile: 12px
-	
 
+#### Export, title and alt
+
+Every exported image:
+
+* has `webp` (preferable) or `jpg` format
+* has around 50-150kb. Only images where zoomed detail is important could have higher size.
+* has title and alt text (exception: don't add alt text to decorative images like icons that are not part of docs)
+
+e.g. `![image alt text](./myimage.png "image title")`
+
+The image alt text is used to describe images to users who can't see them (they are using a screen-reader or image failed to load). The image title attribute is only visible on mouse-over and displays just the title over image.
+
+For texts:
+
+* Usually, use the same for alt and titles
+* Include text that's part of the image
+* Use keywords sparingly - describe in simple words
+* Never start with “Image of …” or “Picture of …”
+* Be specific and succinct
 
 #### Referencing
 
  - Do not add `docs` prefix (base)
  - Place images next to the markdown files that reference them
  - Do not start with `/`, use relative paths
 
-e.g. `![](./myimage.png)` if the image is in the same folder as your markdown file
+e.g. `![image alt text](./myimage.png "image title")` if the image is in the same folder as your markdown file
 
  - For global pictures/assets placed in `src/.vuepress/public` use custom component `<PublicImage />`
 
-e.g. `<PublicImage src="MM_logo_HORIZ_color.svg" />`
+e.g. `<PublicImage src="MM_logo_HORIZ_color.svg" title="Mergin Maps logo"/>`
 
-<PublicImage src="MM_logo_HORIZ_color.svg" />
+<PublicImage src="MM_logo_HORIZ_color.svg" title="Mergin Maps logo" />
 
 ### Table of Contents