dumbymap

Generate interactive maps from Semantic HTML
git clone git://git.topo.tw/dumbymap
Log | Files | Refs | README

README.md (5875B)

      1 # Dumbymap
      2 
      3 This library generate web maps from [Semantic HTML], just play around with [demo page](https://outdoorsafetylab.github.io/dumbymap/)
      4 
      5 > [!IMPORTANT]
      6 > For build steps about firefox addon, please visit `DEVELOPING.md`
      7 
      8 > [!CAUTION]
      9 > DumbyMap is not in production stage. API is not stable now, use it carefully
     10 
     11 ## Getting Started
     12 
     13 Browser (CDN):
     14 - unpkg: https://unpkg.com/dumbymap@latest/dist/dumbymap.mjs
     15 
     16 Node.js:
     17 
     18 ```bash
     19 npm install dumbymap
     20 ```
     21 ```js
     22 import { markdown2HTML, generateMaps } from 'dumbymap'
     23 
     24 // Create container element
     25 const container = document.createElement('div')
     26 document.body.append(container)
     27 
     28 // Convert markdown text into Semantic HTML
     29 markdown2HTML(container, '# Heading\n\n```map\nid: foo\nuse: Maplibre\n```\n')
     30 
     31 // Gernerate maps from code block
     32 const dumbymap = generateMaps(container, options ?? {})
     33 ```
     34 
     35 For more information, please visie [docs page](https://outdoorsafetylab.github.io/dumbymap/docs/global.html#generateMaps)
     36 
     37 
     38 ## Semantic HTML
     39 
     40 Dumbymap adds several features from contents of Semantic HTML:
     41 
     42 ### Code Block for map
     43 
     44 Generated from Element fits CSS Selector `:has(.language-map)` (by default)
     45 
     46 It generates maps by `textContent` in YAML format, done by [mapclay]
     47 
     48 For example:
     49 ~~~markdown
     50 <!-- Markdown Text -->
     51 ```map
     52 use: Maplibre
     53 width: 200px
     54 ```
     55 
     56 <!-- HTML -->
     57 <pre><code class="language-map">use: Maplibre
     58 width: 200px</code></pre>
     59 ~~~
     60 
     61 ### DocLink
     62 
     63 Generated from anchor element which:
     64 1. With has link for [document fragment](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#linking_to_an_element_on_the_same_page).
     65 2. With title starts from `=>`
     66 3. The following text in title would be treated as CSS selector of target element
     67 
     68 It shows leader-line to target element on hover, for example:
     69 
     70 ```markdown
     71 <!-- Markdown Text -->
     72 [link](#TEXT "=>.random-class")
     73 
     74 <!-- Anchor Element -->
     75 <a href="#TEXT" title="=>.random-class">link</a>
     76 ```
     77 
     78 Generated from anchor element which:
     79 1. With has link for [document fragment](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#linking_to_an_element_on_the_same_page). 
     80 2. With title starts from `=>`
     81 3. The following text of title would be treated as CSS selector of target element
     82 
     83 Class name `with-leader-line` and `doclink` would be added to element.
     84 
     85 It shows leader-line to target element on hover, for example:
     86 
     87 ```markdown
     88 <!-- Markdown Text -->
     89 [link](#TEXT "=>.random-class")
     90 
     91 <!-- Anchor Element -->
     92 <a href="#TEXT" title="=>.random-class">link</a>
     93 
     94 
     95 <!-- Links above is transfered to this -->
     96 <a class="with-leader-line doclink" href="#TEXT" title="=>.random-class">link</a>
     97 ```
     98 
     99 ### GeoLink
    100 
    101 Generated from anchor element with [geo URI scheme](https://en.wikipedia.org/wiki/Geo_URI_scheme).
    102 Class name `with-leader-line` and `geolink` would be added to element.
    103 
    104 It show leader-line to coordinates in target map elements, for example:
    105 
    106 ```markdown
    107 <!-- markdown text -->
    108 [Taiwan](geo:24,121)
    109 
    110 <!-- anchor element -->
    111 <a href="geo:24,121">Taiwan</a>
    112 
    113 
    114 <!-- Links above is transfered to this -->
    115 <a class="with-leader-line geolink" href="geo:24,121">Taiwan</a>
    116 ```
    117 
    118 It changes behaviors by query parameters in link:
    119 1. If `xy` is specified, GeoLink would use its value instead of value in geo URI scheme
    120 1. If `id` is specified, GeoLink would only points to map with its value. Can use comma to add multiple id
    121 1. If `type` is specified, anchor on map changes appearance (now only support `type=circle`)
    122 
    123 For example:
    124 ```html
    125 <!-- The following link points to coordinates [274527,2665529] in map element "map1" and "map2"
    126 <a href="geo:24,121?xy=274527,2665529&id=map1,map2">Taiwan</a>
    127 ```
    128 
    129 If `title` of element is specified, leader-line use it as label, for example:
    130 ```markdown
    131 <!-- markdown text -->
    132 [Taiwan](geo:24,121 "Here it is!")
    133 
    134 <!-- anchor element -->
    135 <a href="geo:24,121" title="Here it is!">Taiwan</a>
    136 ```
    137 
    138 ## Structure
    139 
    140 After `generateMaps()`, the container has the following structure:
    141 
    142 ![structure](./assets/structure_1.jpg)
    143 
    144 For each element:
    145 * `class="Dumby"`: Container of DumbyMap Contents. It uses attribute `data-layout` to switch layout
    146 * `class="SemanticHtml"`: Container of Semantic HTML
    147 * `class="Showcase"`: Container of map with `class="focus"`. Some layouts use it to display focused map
    148 * `class="dumby-block"`: Block contains part of contents of Semantic HTML.
    149 * `class="mapclay"`: Map generated by [mapclay]
    150 
    151 ## Layouts
    152 
    153 Dumbymap switch layouts by attribute `data-layout` of container. Most of the features are done by pure CSS.
    154 
    155 You can add custom layout by options `layouts`. For example, the following code add a new layout `sticky` to stick `Showcase` at bottom right corner:
    156 
    157 ```css
    158 .Dumby[data-layout='sticky'] {
    159   max-width: 80em;
    160 
    161   .Showcase {
    162     display: block;
    163     width: 20vw;
    164     height: 40vh;
    165     position: absolute;
    166     right: 20px;
    167     bottom: 20px;
    168     background: red;
    169   }
    170 }
    171 ```
    172 
    173 ```js
    174 generateMaps(container, { layouts: "sticky" })
    175 ```
    176 
    177 <details><summary>Result:</summary>
    178 
    179 ![](./assets/layout-example1.png)
    180 
    181 </details>
    182 
    183 
    184 ## Dependencies
    185 
    186 - [leader-line](https://anseki.github.io/leader-line/)
    187 - [plain-draggable](https://anseki.github.io/plain-draggable/)
    188 - [markdown-it](https://github.com/markdown-it/markdown-it/)
    189 - [mapclay]
    190 - [EasyMDE](https://github.com/Ionaru/easy-markdown-editor)
    191 
    192 
    193 ## Motivation
    194 
    195 * Respect Semantic HTML
    196 * User Friendly: The target audience includes Hikers, Outdoor Workers
    197 * Easy to Extend: Can co-work with various of Modern Map Libraries, no one dominates
    198 * [Designed to Last](https://jeffhuang.com/designed_to_last/)
    199 
    200 ## See Also
    201 
    202 * [obsidian-map-view](https://github.com/esm7/obsidian-map-view)
    203 * [odyssey.js](http://cartodb.github.io/odyssey.js/)
    204 * [StoryMapJS](https://storymap.knightlab.com/)
    205 
    206 [mapclay]: https://github.com/outdoorsafetylab/mapclay
    207 [Semantic HTML]: https://developer.mozilla.org/en-US/docs/Glossary/Semantics#semantics_in_html