From e4f6b7ecd5872d1ec80d3aa961ffa93708291224 Mon Sep 17 00:00:00 2001
From: Hsieh Chin Fan <pham@topo.tw>
Date: Fri, 4 Oct 2024 16:01:22 +0800
Subject: docs: update README

---
 README.md | 129 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 117 insertions(+), 12 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 4bde800..3296bd5 100644
--- a/README.md
+++ b/README.md
@@ -20,20 +20,124 @@ document.body.append(container)
 markdown2HTML(container, '# Heading\n\n```map\nid: foo\nuse: Maplibre\n```\n')
 
 // Gernerate maps from code block
-generateMaps(container)
+const dumbymap = generateMaps(container)
 ```
 
 Browser (CDN):
 - unpkg: https://unpkg.com/dumbymap@latest/dist/dumbymap.mjs
 
+## Semantic HTML
+
+Dumbymap adds several features by Semantic HTML:
+
+### Code Block for map
+
+Generated from Element fits CSS Selector `:has(.language-map)`
+
+It generates maps by `textContent` in YAML format, done by [`mapclay`](/outdoorsafetylab/mapclay).
+
+For example:
+~~~markdown
+<!-- Markdown Text -->
+```map
+use: Maplibre
+width: 200px
+```
+
+<!-- HTML -->
+<pre><code class="language-map">use: Maplibre
+width: 200px</code></pre>
+~~~
+
+### DocLink
+
+Generated from anchor element which:
+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).
+2. With title starts from `=>`
+3. The following text in title would be treated as CSS selector of target element
+
+It shows leader-line to target element on hover, for example:
+
+```markdown
+<!-- Markdown Text -->
+[link](#TEXT "=>.random-class")
+
+<!-- Anchor Element -->
+<a href="#TEXT" title="=>.random-class">link</a>
+```
+
+Generated from anchor element which:
+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). 
+2. With title starts from `=>`
+3. The following text of title would be treated as CSS selector of target element
+
+Class name `with-leader-line` and `doclink` would be added to element.
+
+It shows leader-line to target element on hover, for example:
+
+```markdown
+<!-- Markdown Text -->
+[link](#TEXT "=>.random-class")
+
+<!-- Anchor Element -->
+<a href="#TEXT" title="=>.random-class">link</a>
+
+
+<!-- Links above is transfered to this -->
+<a class="with-leader-line doclink" href="#TEXT" title="=>.random-class">link</a>
+```
+
+### GeoLink
+
+Generated from anchor element with [geo URI scheme](https://en.wikipedia.org/wiki/Geo_URI_scheme).
+Class name `with-leader-line` and `geolink` would be added to element.
+
+It show leader-line to coordinates in target map elements, for example:
+
+```markdown
+<!-- markdown text -->
+[Taiwan](geo:24,121)
+
+<!-- anchor element -->
+<a href="geo:24,121" title="Here it is!">Taiwan</a>
+
+
+<!-- Links above is transfered to this -->
+<a class="with-leader-line geolink" href="geo:24,121" title="Here it is!">Taiwan</a>
+```
+
+It changes behaviors by query parameters in link:
+1. If `xy` is specified, GeoLink would use its value instead of value in geo URI scheme
+2. If `id` is specified, GeoLink would only points to map with its value. Can use comma to add multiple id
+
+For example:
+```html
+<!-- The following link points to coordinates [274527,2665529] in map element "map1" and "map2"
+<a href="geo:24,121?xy=274527,2665529&id=map1,map2" title="Here it is!">Taiwan</a>
+```
+
 ## Structure
 
 After `generateMaps()`, the container has the following structure:
 
 ![structure](./assets/structure_1.jpg)
 
+## Layouts
+
+Dumbymap switch layouts by attribute `data-layout` of container. Most of the features are done by pure CSS.
+
+You can add custom layout by options `layouts`:
+
+```js
+generateMaps(container, {
+  layouts: [
+    "LAYOUT-NAME"
+  ]
+})
+```
+
 
-## Depandencies
+## Dependencies
 
 - [leader-line](https://anseki.github.io/leader-line/)
 - [plain-draggable](https://anseki.github.io/plain-draggable/)
@@ -42,14 +146,15 @@ After `generateMaps()`, the container has the following structure:
 - [EasyMDE](https://github.com/Ionaru/easy-markdown-editor)
 
 
-## TODOs
+## Motivation
+
+* Respect Semantic HTML
+* User Friendly: The target audience includes Hikers, Outdoor Workers
+* Easy to Extend: Can co-work with various of Modern Map Libraries, no one dominates
+* [Designed to Last](https://jeffhuang.com/designed_to_last/)
+
+## See Also
 
-- Semantic HTML
-  - context menu for add geolinks
-- Editor
-  - Reduce fontawesome resources
-  - Better way to edit table in markdown
-- Export
-  - Executable HTML file with data URI
-- Misc
-  - Add favicon
+* [obsidian-map-view](https://github.com/esm7/obsidian-map-view)
+* [odyssey.js](http://cartodb.github.io/odyssey.js/)
+* [StoryMapJS](https://storymap.knightlab.com/)
-- 
cgit v1.2.3-70-g09d2