diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
new file mode 100644
index 0000000..9c54df5
--- /dev/null
+++ b/.github/workflows/deploy.yml
@@ -0,0 +1,52 @@
+name: Deploy
+on:
+  push:
+    branches:
+      - doc # TODO: change to tag only
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # To push a branch
+      pages: write    # To push to a GitHub Pages site
+      id-token: write # To update the deployment status
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Install latest mdbook
+        run: |
+          tag=$(curl 'https://api.github.com/repos/rust-lang/mdbook/releases/latest' | jq -r '.tag_name')
+          url="https://github.com/rust-lang/mdbook/releases/download/${tag}/mdbook-${tag}-x86_64-unknown-linux-gnu.tar.gz"
+          mkdir mdbook
+          curl -sSL $url | tar -xz --directory=./mdbook
+          echo `pwd`/mdbook >> $GITHUB_PATH
+      # - name: Install latest mdbook-pagetoc
+      #   run: |
+      #     tag=$(curl 'https://api.github.com/repos/slowsage/mdbook-pagetoc/releases/latest' | jq -r '.tag_name')
+      #     url="https://github.com/slowsage/mdbook-pagetoc/releases/download/${tag}/mdbook-pagetoc-${tag}-x86_64-unknown-linux-gnu.tar.gz"
+      #     curl -sSL $url | tar -xz --directory=./mdbook
+      - name: Install latest mdbook-pagetoc
+        uses: baptiste0928/cargo-install@v2
+        with:
+          crate: mdbook-pagetoc
+          locked: false
+      - name: Run tests
+        run: |
+          cd doc
+          mdbook test
+      - name: Build Book
+        run: |
+          cd doc
+          mdbook build
+      - name: Setup Pages
+        uses: actions/configure-pages@v2
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          # Upload entire repository
+          path: 'doc/book'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1
\ No newline at end of file
diff --git a/README.md b/README.md
index 3a0d204..9ff6444 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1 @@
 # Sitemap Web Scraper
-
-## Bash completion
-
-Source the completion script in your `~/.bashrc` file:
-
-```bash
-echo 'source <(sws completion)' >> ~/.bashrc
-```
diff --git a/doc/.gitignore b/doc/.gitignore
new file mode 100644
index 0000000..927206b
--- /dev/null
+++ b/doc/.gitignore
@@ -0,0 +1,4 @@
+book
+theme/index.hbs
+theme/pagetoc.css
+theme/pagetoc.js
\ No newline at end of file
diff --git a/doc/book.toml b/doc/book.toml
new file mode 100644
index 0000000..d155b15
--- /dev/null
+++ b/doc/book.toml
@@ -0,0 +1,12 @@
+[book]
+authors = ["Romain Leroux"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Sitemap Web Scraper"
+
+# https://crates.io/crates/mdbook-pagetoc
+[preprocessor.pagetoc]
+[output.html]
+additional-css = ["theme/pagetoc.css"]
+additional-js  = ["theme/pagetoc.js"]
\ No newline at end of file
diff --git a/doc/src/README.md b/doc/src/README.md
new file mode 100644
index 0000000..c4aaf31
--- /dev/null
+++ b/doc/src/README.md
@@ -0,0 +1,39 @@
+# Introduction
+
+Sitemap Web Scraper, or [sws][], is a tool for simple, flexible, and yet performant web
+pages scraping. It consists of a [CLI][] that executes a [Lua][] [JIT][lua-jit] script
+and outputs a [CSV][] file.
+
+All the logic for crawling/scraping is defined in Lua and executed on a multiple threads
+in [Rust][]. The actual parsing of HTML is done in Rust. Standard [CSS
+selectors][css-sel] are also implemented in Rust (using Servo's [html5ever][] and
+[selectors][]). Both functionalities are accessible through a Lua API for flexible
+scraping logic.
+
+As for the crawling logic, multiple seeding options are available: [robots.txt][robots],
+[sitemaps][], or a custom HTML pages list. By default, sitemaps (either provided or
+extracted from `robots.txt`) will be crawled recursively and the discovered HTML pages
+will be scraped with the provided Lua script. It's also possible to dynamically add page
+links to the crawling queue when scraping an HTML page. See the [crawl][sub-crawl]
+subcommand and the [Lua scraper][lua-scraper] for more details.
+
+Besides, the Lua scraping script can be used on HTML pages stored as local files,
+without any crawling. See the [scrap][sub-scrap] subcommand doc for more details.
+
+Furthermore, the CLI is composed of `crates` that can be used independently in a custom
+Rust program.
+
+[sws]: https://github.com/lerouxrgd/sws
+[cli]: https://en.wikipedia.org/wiki/Command-line_interface
+[rust]: https://www.rust-lang.org/
+[lua]: https://www.lua.org/
+[lua-jit]: https://luajit.org/
+[csv]: https://en.wikipedia.org/wiki/Comma-separated_values
+[css-sel]: https://www.w3schools.com/cssref/css_selectors.asp
+[html5ever]: https://crates.io/crates/html5ever
+[selectors]: https://crates.io/crates/selectors
+[robots]: https://en.wikipedia.org/wiki/Robots.txt
+[sitemaps]: https://www.sitemaps.org/
+[sub-crawl]: ./crawl_overview.html
+[sub-scrap]: ./scrap_overview.html
+[lua-scraper]: ./lua_scraper.html
diff --git a/doc/src/SUMMARY.md b/doc/src/SUMMARY.md
new file mode 100644
index 0000000..3176c5e
--- /dev/null
+++ b/doc/src/SUMMARY.md
@@ -0,0 +1,13 @@
+# Summary
+
+[Introduction](README.md)
+
+[Getting Started](getting_started.md)
+
+- [Subcommand: crawl](./crawl_overview.md)
+  - [Crawler Configuration](./crawl_config.md)
+
+- [Subcommand: scrap](./scrap_overview.md)
+
+- [Lua Scraper](./lua_scraper.md)
+  - [Lua API Overview](./lua_api_overview.md)
diff --git a/doc/src/crawl_config.md b/doc/src/crawl_config.md
new file mode 100644
index 0000000..395b7f1
--- /dev/null
+++ b/doc/src/crawl_config.md
@@ -0,0 +1,83 @@
+# Crawler Config
+
+The crawler configurable parameters are:
+
+| Parameter      | Default                                                                                                                        | Description                                                                                                                                                                                                                      |
+|----------------|--------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| user_agent     | "SWSbot"                                                                                                                       | The `User-Agent` header that will be used in all HTTP requests                                                                                                                                                                   |
+| page_buffer    | 10_000                                                                                                                         | The size of the pages download queue. When the queue is full new downloads are on hold. This parameter is particularly relevant when using concurrent throttling.                                                                |
+| throttle       | `Concurrent(100)` if `robot` is `None` <br><br>Otherwise `Delay(N)` where `N` is read from `robots.txt` field `Crawl-delay: N` | A throttling strategy for HTML pages download. <br><br>`Concurrent(N)` means at max `N` downloads at the same time, `PerSecond(N)` means at max `N` downloads per second, `Delay(N)` means wait for `N` seconds betwen downloads |
+| num_workers    | max(1, num_cpus-2)                                                                                                             | The number of CPU cores that will be used for scraping page in parallel using the provided Lua script.                                                                                                                           |
+| on_dl_error    | `SkipAndLog`                                                                                                                   | Behaviour when an error occurs while downloading an HTML page. Other possible value is `Fail`.                                                                                                                                   |
+| on_xml_error   | `SkipAndLog`                                                                                                                   | Behaviour when an error occurs while processing a XML sitemap. Other possible value is `Fail`.                                                                                                                                   |
+| on_scrap_error | `SkipAndLog`                                                                                                                   | Behaviour when an error occurs while scraping an HTML page in Lua. Other possible value is `Fail`.                                                                                                                               |
+| robot          | `None`                                                                                                                         | An optional `robots.txt` URL used to retrieve a specific `Throttle::Delay`. <br><br>⚠ Conflicts with `seedRobotsTxt` in [Lua Scraper][lua-scraper], meaning that when `robot` is defined the `seed` cannot be a robot too. |
+
+These parameters can be changed through Lua script or CLI arguments.
+
+The priority order is: `CLI (highest priority) > Lua > Default values`
+
+[lua-scraper]: ./lua_scraper.html#seed-definition
+
+## Lua override
+
+You can override parameters in Lua through the global variable `sws.crawlerConfig`.
+
+| Parameter      | Lua name     | Example Lua value                   |
+|----------------|--------------|-------------------------------------|
+| user_agent     | userAgent    | "SWSbot"                            |
+| page_buffer    | pageBuffer   | 10000                               |
+| throttle       | throttle     | { Concurrent = 100 }                |
+| num_workers    | numWorkers   | 4                                   |
+| on_dl_error    | onDlError    | "SkipAndLog"                        |
+| on_xml_error   | onXmlError   | "Fail"                              |
+| on_scrap_error | onScrapError | "SkipAndLog"                        |
+| robot          | robot        | "https://www.google.com/robots.txt" |
+
+
+Here is an example of crawler configuration parmeters set using Lua:
+
+```lua
+-- You don't have to specify all parameters, only the ones you want to override.
+sws.crawlerConfig = {
+  userAgent = "SWSbot",
+  pageBuffer = 10000,
+  throttle = { Concurrent = 100 }, -- or: { PerSecond = 100 }, { Delay = 2 }
+  numWorkers = 4,
+  onDlError = "SkipAndLog", -- or: "Fail"
+  onXmlError = "SkipAndLog",
+  onScrapError = "SkipAndLog",
+  robot = nil,
+}
+```
+
+## CLI override
+
+You can override parameters through the CLI arguments.
+
+| Parameter            | CLI argument name | Example CLI argument value          |
+|----------------------|-------------------|-------------------------------------|
+| user_agent           | --user-agent      | 'SWSbot'                            |
+| page_buffer          | --page-buffer     | 10000                               |
+| throttle (Concurent) | --conc-dl         | 100                                 |
+| throttle (PerSecond) | --rps             | 10                                  |
+| throttle (Delay)     | --delay           | 2                                   |
+| num_workers          | --num-workers     | 4                                   |
+| on_dl_error          | --on-dl-error     | skip-and-log                        |
+| on_xml_error         | --on-xml-error    | fail                                |
+| on_scrap_error       | --on-scrap-error  | skip-and-log                        |
+| robot                | --robot           | 'https://www.google.com/robots.txt' |
+
+Here is an example of crawler configuration parmeters set using CLI arguments:
+
+```sh
+sws --script path/to/scrape_logic.lua -o results.csv     \
+    --user-agent     'SWSbot'                            \
+    --page-buffer    10000                               \
+    --conc-dl        100                                 \
+    --num-workers    4                                   \
+    --on-dl-error    skip-and-log                        \
+    --on-xml-error   fail                                \
+    --on-scrap-error skip-and-log                        \
+    --robot          'https://www.google.com/robots.txt' \
+```
diff --git a/doc/src/crawl_overview.md b/doc/src/crawl_overview.md
new file mode 100644
index 0000000..109b56f
--- /dev/null
+++ b/doc/src/crawl_overview.md
@@ -0,0 +1,23 @@
+# Subcommand: crawl
+
+```text
+Crawl sitemaps and scrap pages content
+
+Usage: sws crawl [OPTIONS] --script <SCRIPT>
+
+Options:
+  -s, --script <SCRIPT>
+          Path to the Lua script that defines scraping logic
+  -o, --output-file <OUTPUT_FILE>
+          Optional file that will contain scraped data, stdout otherwise
+      --append
+          Append to output file
+      --truncate
+          Truncate output file
+  -q, --quiet
+          Don't output logs
+  -h, --help
+          Print help information
+```
+
+More options in [CLI override](./crawl_config.md#cli-override)
diff --git a/doc/src/getting_started.md b/doc/src/getting_started.md
new file mode 100644
index 0000000..ba7675d
--- /dev/null
+++ b/doc/src/getting_started.md
@@ -0,0 +1,85 @@
+# Getting Started
+
+## Get the binary
+
+Download the latest standalone binary for your OS on the [release][] page, and put it in
+a location available in your `PATH`.
+
+[release]: https://github.com/lerouxrgd/sws/releases
+
+## Basic example
+
+Let's create a simple `urbandict.lua` scraper for [Urban Dictionary][ud]. Copy paste the
+following command:
+
+```sh
+cat << 'EOF' > urbandict.lua
+sws.seedPages = {
+   "https://www.urbandictionary.com/define.php?term=Lua"
+}
+
+function scrapPage(page, context)
+   for defIndex, def in page:select("section .definition"):enumerate() do
+      local word = def:select("h1 a.word"):iter()()
+      if not word then
+         word = def:select("h2 a.word"):iter()()
+      end
+      if not word then
+         goto continue
+      end
+      word = word:innerHtml()
+
+      local contributor = def:select(".contributor"):iter()()
+      local date = string.match(contributor:innerHtml(), ".*\\?</a>%s*(.*)\\?")
+      date = sws.Date(date, "%B %d, %Y"):format("%Y-%m-%d")
+
+      local meaning = def:select(".meaning"):iter()()
+      meaning = meaning:innerText():gsub("[\n\r]+", " ")
+
+      local example = def:select(".example"):iter()()
+      example = example:innerText():gsub("[\n\r]+", " ")
+
+      if word and date and meaning and example then
+         local record = sws.Record()
+         record:pushField(word)
+         record:pushField(defIndex)
+         record:pushField(date)
+         record:pushField(meaning)
+         record:pushField(example)
+         context:sendRecord(record)
+      end
+
+      ::continue::
+   end
+end
+EOF
+```
+
+You can then run it with:
+
+```sh
+sws crawl --script urbandict.lua
+```
+
+As we have defined `sws.seedPages` to be a single page (that is [Urban Dictionary's
+Lua][ud-lua] definition), the `scrapPage` function will be run on that single page
+only. There are multiple seeding options which are detailed in the [Lua scraper - Seed
+definition][lua-scraper] section.
+
+By default the resulting csv file is written to stdout, however the `-o` (or
+`--output-file`) lets us specify a proper output file. Note that this file can be also
+be appended or truncated, using the additional flags `--append` or `--truncate`
+respectively. See the [crawl subcommand][crawl-doc] section for me details.
+
+[ud]: https://www.urbandictionary.com/
+[ud-lua]: https://www.urbandictionary.com/define.php?term=Lua
+[lua-scraper]: ./lua_scraper.html#seed-definition
+[crawl-doc]: ./crawl_overview.html
+
+## Bash completion
+
+You can source the completion script in your `~/.bashrc` file with:
+
+```bash
+echo 'source <(sws completion)' >> ~/.bashrc
+```
diff --git a/doc/src/lua_api_overview.md b/doc/src/lua_api_overview.md
new file mode 100644
index 0000000..aa70afb
--- /dev/null
+++ b/doc/src/lua_api_overview.md
@@ -0,0 +1,162 @@
+# Lua API Overview
+
+<style>
+  table {
+    width: 100%;
+  }
+  th {
+    white-space: nowrap;
+    text-align: left;
+  }
+  td:nth-child(1) {
+    white-space: nowrap;
+  }
+</style>
+
+## Global variables
+
+| Lua name  | Lua Type | Description                                                                                                                                          |
+|-----------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------|
+| scrapPage | function | Define the scraping logic for a single HTML page. See [details](./lua_scraper.html#function-accepturl)                                               |
+| acceptUrl | function | Specify whether to accept a URL when crawling an [XML Sitemap][xml-sitemap], `true` by default. See [details](./lua_scraper.html#function-scrappage) |
+| sws       | table    | The sws namespace                                                                                                                                    |
+
+[xml-sitemap]: https://en.wikipedia.org/wiki/Site_map
+
+## Namespaced variables
+
+All the following variables are defined in the `sws` table.
+
+### Seeds
+
+The configurable [seed](./lua_scraper.html#seed-definition)
+
+| Lua name      | Lua Type | Description              |
+|---------------|----------|--------------------------|
+| seedSitemaps  | table    | A list of sitemap URLs   |
+| seedPages     | table    | A list of HTML page URLs |
+| seedRobotsTxt | string   | A single robots.txt URL  |
+
+### Configurations
+
+| Lua name        | Lua Type | Description                                                                           |
+|-----------------|----------|---------------------------------------------------------------------------------------|
+| csvWriterConfig | table    | Config used to write output csv records. See [details](./lua_scraper.html#csv-record) |
+| crawlerConfig   | table    | Config used to customize crawler behavior. See [details](./crawl_config.html)         |
+
+## Types
+
+All types are defined in the `sws` table.
+
+### Class Html
+
+A parsed HTML page. Its HTML elements can be selected with [CSS selectors](./lua_scraper.html#css-selectors).
+
+| Lua signature                           | Description                                                                    |
+|-----------------------------------------|--------------------------------------------------------------------------------|
+| Html:select(selector: string) -> Select | Parses the given CSS `selector` and returns a [Select](#class-select) instance |
+| Html:root() -> ElemRef                  | Returns an [ElemRef](#class-elemref) to the HTML root node                     |
+
+### Class Select
+
+A selection made with [CSS selectors](./lua_scraper.html#css-selectors). Its HTML elements can be iterated.
+
+| Lua signature                                      | Description                                                                             |
+|----------------------------------------------------|-----------------------------------------------------------------------------------------|
+| Select:iter() -> iterator&lt;ElemRef&gt;           | An iterator of [ElemRef](#class-elemref) over the selected HTML nodes                   |
+| Select:enumerate() -> iterator<(integer, ElemRef)> | An iterator of [ElemRef](#class-elemref) and their indices over the selected HTML nodes |
+
+### Class ElemRef
+
+An HTML element reference. Its descendant HTML elements can be selected with [CSS selectors](./lua_scraper.html#css-selectors).
+
+| Lua signature                              | Description                                                                                         |
+|--------------------------------------------|-----------------------------------------------------------------------------------------------------|
+| ElemRef:select(selector: string) -> Select | Parses the given CSS `selector` and returns a [Select](#class-select) instance over its descendants |
+| ElemRef:innerHtml() -> string              | The inner HTML string of this element                                                               |
+| ElemRef:innerText() -> string              | Returns all the descendent text nodes content concatenated                                          |
+| ElemRef:name() -> string                   | The HTML element name                                                                               |
+| ElemRef:id() -> string                     | The HTML element id, if any                                                                         |
+| ElemRef:hasClass(class: string) -> boolean | Whether the HTML element has the given `class`                                                      |
+| ElemRef:classes() -> table                 | Returns all classes of the HTML element                                                             |
+| ElemRef:attr(name: string) -> string       | If the HTML element has the `name` attribute, return its value, nil otherwise                       |
+| ElemRef:attrs() -> table                   | Returns all attributes of the HTML element                                                          |
+
+### Class Date
+
+A helper class for parsing and formatting dates.
+
+| Lua signature                           | Description                                                                                                         |
+|-----------------------------------------|---------------------------------------------------------------------------------------------------------------------|
+| Date(date: string, fmt: string) -> Date | Parses the given `date` accordingly to `fmt`, uses [chrono::NaiveDate::parse_from_str][chrono-parse] under the hood |
+| Date:format(fmt: string) -> string      | Formats the current date accordingly to `fmt`, uses [chrono::NaiveDate::format][chrono-format] under the hood       |
+
+[chrono-parse]: https://docs.rs/chrono/latest/chrono/naive/struct.NaiveDate.html#method.parse_from_str
+[chrono-format]: https://docs.rs/chrono/latest/chrono/naive/struct.NaiveDate.html#method.format
+
+### Class ScrapingContext
+
+The context available when an HTML page is scraped, provided as parameter in [scrapPage](./lua_scraper.html#function-scrappage)
+
+| Lua signature                                  | Description                                                                                                 |
+|------------------------------------------------|-------------------------------------------------------------------------------------------------------------|
+| ScrapingContext:pageLocation() -> PageLocation | Returns the current [PageLocation](#class-pagelocation)                                                     |
+| ScrapingContext:sendRecord(rec: Record)        | Sends a CSV [Record](#class-record) to the current output (either `stdout` or the specified output file)    |
+| ScrapingContext:sendUrl(url: string)           | Adds the given `url` to the internal crawling queue so that it will be scraped later                        |
+| ScrapingContext:workerId() -> string           | A string identifying the current worker thread. It simply consists of the worker's number (starting from 0) |
+| ScrapingContext:robot() -> Robot               | Returns current [Robot](#class-robot) if it was [setup](./lua_scraper.html#robot-definition), nil otherwise |
+
+### Class PageLocation
+
+The location of an HTML page.
+
+| Lua signature                                 | Description                                                                                                 |
+|-----------------------------------------------|-------------------------------------------------------------------------------------------------------------|
+| PageLocation:kind() -> option&lt;Location&gt; | Get the page's [Location](#enum-location) kind                                                              |
+| PageLocation:get() -> option&lt;string&gt;    | If the current page is a `Location.URL` returns its URL, if it's a `Location.PATH` returns its path on disk |
+
+### Enum Location
+
+Location kind.
+
+| Lua variant   | Description                                                                                     |
+|---------------|-------------------------------------------------------------------------------------------------|
+| Location.URL  | A URL location kind (remote). Relevant when using the [crawl subcommand](./crawl_overview.html) |
+| Location.PATH | A PATH location kind (local). Relevant when using the [scrap subcommand](./scrap_overview.html) |
+
+### Class Record
+
+A dynamic CSV record. CSV formatting can be customized (see [details](./lua_scraper.html#csv-record)).
+
+| Lua signature                   | Description                                     |
+|---------------------------------|-------------------------------------------------|
+| Record() -> Record              | Creates a new empty CSV record                  |
+| Record:pushField(field: string) | Adds the given `field` value to this CSV record |
+
+### Class CrawlingContext
+
+The context available when an XML Sitemap page is crawled, provided as parameter in [acceptUrl](./lua_scraper.html#function-accepturl)
+
+| Lua signature                        | Description                                                                                                 |
+|--------------------------------------|-------------------------------------------------------------------------------------------------------------|
+| CrawlingContext:robot() -> Robot     | Returns current [Robot](#class-robot) if it was [setup](./lua_scraper.html#robot-definition), nil otherwise |
+| CrawlingContext:sitemap() -> Sitemap | The [Sitemap](#enum-sitemap) format of the sitemap page being crawled                                       |
+
+### Class Robot
+
+| Lua signature                         | Description                                                                                                            |
+|---------------------------------------|------------------------------------------------------------------------------------------------------------------------|
+| Robot:allowed(url: string) -> boolean | Whether the given `url` is allowed for crawling or not. This relies on [texting_robots::Robot::allowed][robot-allowed] |
+
+[robot-allowed]: https://docs.rs/texting_robots/latest/texting_robots/struct.Robot.html#method.allowed
+
+### Enum Sitemap
+
+The [Sitemaps formats][sm-format] of an XML Sitemap page.
+
+| Lua variant     | Description               |
+|-----------------|---------------------------|
+| Sitemap.INDEX   | A `<sitemapindex>` format |
+| Sitemap.URL_SET | A `<urlset>` format       |
+
+[sm-format]: https://en.wikipedia.org/wiki/Sitemaps#File_format
diff --git a/doc/src/lua_scraper.md b/doc/src/lua_scraper.md
new file mode 100644
index 0000000..24efe8e
--- /dev/null
+++ b/doc/src/lua_scraper.md
@@ -0,0 +1,246 @@
+# Lua Scraper
+
+The scraping logic is configured through a single `Lua` script.
+
+The customizable parameters are:
+* [seed](#seed-definition): Defines the seed pages for crawling
+* [acceptUrl](#function-accepturl): A function to specify whether to accept a URL
+  when crawling an [XML Sitemap][xml-sitemap]
+* [scrapPage](#function-scrappage): A function that defines the scraping logic for a
+  single HTML page
+
+[xml-sitemap]: https://en.wikipedia.org/wiki/Site_map
+
+## Seed definition
+
+The [seed](./lua_api_overview.html#seeds) be one of `seedSitemaps`, `seedPages`, or
+`seedRobotsTxt`.
+
+Defining a `seed` is always **mandatory**. However, when using the [scrap
+subcommand](./scrap_overview.html) it will be ignored as the input will be either the
+specified URL or the specified local files.
+
+⚠️ Defining multiple `seeds` will throw an **error** ⚠️
+
+### Example
+
+```lua
+-- A list of sitemap URLs (gzipped sitemaps are supported)
+sws.seedSitemaps = {
+   "https://www.urbandictionary.com/sitemap-https.xml.gz"
+}
+```
+
+```lua
+-- A list of HTML pages
+sws.seedPages = {
+   "https://www.urbandictionary.com/define.php?term=Rust",
+   "https://www.urbandictionary.com/define.php?term=Lua",
+}
+```
+
+```lua
+-- A single robots.txt URL
+sws.seedRobotsTxt = "https://www.urbandictionary.com/robots.txt"
+```
+
+## Robot definition
+
+A [robots.txt][robots-txt] can be used either as:
+
+* A crawling seed through `sws.seedRobotsTxt` (see [above](#example))
+
+* A URL validation helper through `sws.crawlerConfig`'s parameter `robot` (see [crawler
+  configuration](./crawl_config.html))
+
+In both cases, the resulting [Robot](./lua_api_overview.html#class-robot) can be used to
+check whether a given URL is crawlable. This `Robot` is available through both
+[CrawlingContext](./lua_api_overview.html#class-crawlingcontext) (in
+[acceptUrl](#function-accepturl)), and
+[ScrapingContext](./lua_api_overview.html#class-scrapingcontext) (in
+[scrapPage](#function-scrappage)).
+
+The underlying `Robot` implementation in Rust is using the crate
+[texting_robots][robots-rs].
+
+Defining a `robot` is **optional**.
+
+[robots-txt]: https://en.wikipedia.org/wiki/Robots.txt
+[robots-rs]: https://docs.rs/texting_robots/latest/texting_robots/index.html
+
+## Function acceptUrl
+
+```lua
+function acceptUrl(url, context)
+```
+
+A `Lua` function to specify whether to accept a URL when crawling an [XML
+Sitemap][xml-sitemap]. Its parameters are:
+
+* **url:** A URL `string` that is a candidate for crawling/scraping
+
+* **context:** An instance of
+  [CrawlingContext](./lua_api_overview.html#class-crawlingcontext)
+
+Defining `acceptUrl` is **optional**.
+
+[sm-format]: https://en.wikipedia.org/wiki/Sitemaps#File_format
+
+### Example
+
+From `examples/urbandict.lua`:
+
+```lua
+function acceptUrl(url, context)
+   if context:sitemap() == sws.Sitemap.URL_SET then
+      return string.find(url, "term=")
+   else
+      -- For sws.Sitemap.INDEX accept all entries
+      return true
+   end
+end
+```
+
+## Function scrapPage
+
+```lua
+function scrapPage(page, context)
+```
+
+A `Lua` function that defines the scraping logic for a single page. Its parameters are:
+
+* **page:** The [Html](./lua_api_overview.html#class-html) page being scraped
+
+* **context:** An instance of
+  [ScrapingContext](./lua_api_overview.html#class-scrapingcontext)
+
+Defining `scrapPage` is **mandatory**.
+
+#### CSS Selectors
+
+CSS selectors are the most powerful feature of this scraper, they are used to target and
+extract HTML elements in a flexible and efficient way. You can read more about CSS
+selectors on [MDN doc][css-sel-mdn], and find a good reference on [W3C
+doc][css-sel-w3c].
+
+```lua
+function scrapPage(page, context)
+   for i, def in page:select("section .definition"):enumerate() do
+      local word = def:select("h1 a.word"):iter()()
+      print(string.format("Definition %i: %s", i, word))
+   end
+end
+```
+
+The `select` method is expecting a CSS selector string, its result can be either
+iterated or enumerated with `iter` and `enumerate` respectively. Interestingly, the
+elements being iterated over allow for sub selection as they also have a `select`
+method, this enables very flexible HTML elements selection.
+
+See more details in the reference for the [Select](./lua_api_overview.html#class-select)
+class.
+
+[css-sel-mdn]: https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors
+[css-sel-w3c]: https://www.w3schools.com/cssref/css_selectors.php
+
+#### Utils
+
+Some utility functions are also exposed in `Lua`.
+
+* Date utils:
+
+  The [Date](./lua_api_overview.html#class-date) helper can parse and format dates:
+
+  ```lua
+  local date = "March 18, 2005" -- Extracted from some page's element
+  date = sws.Date(date, "%B %d, %Y"):format("%Y-%m-%d") -- Now date is "2005-03-18"
+  ```
+
+  Under the hood a `Date` wraps a Rust [chrono::NaiveDate][chrono-date] that is created
+  using [NaiveDate::parse_from_str][chrono-fmt]. The `format` method will return a
+  string formatted with the specified format (see [specifiers][chrono-specifiers] for
+  the formatting options).
+
+[chrono-date]: https://docs.rs/chrono/latest/chrono/naive/struct.NaiveDate.html
+[chrono-fmt]: https://docs.rs/chrono/latest/chrono/struct.DateTime.html#method.parse_from_str
+[chrono-specifiers]: https://docs.rs/chrono/latest/chrono/format/strftime/index.html
+
+### Example
+
+From `examples/urbandict.lua`:
+
+```lua
+function scrapPage(page, context)
+   for defIndex, def in page:select("section .definition"):enumerate() do
+      local word = def:select("h1 a.word"):iter()()
+      if not word then
+         word = def:select("h2 a.word"):iter()()
+      end
+      if not word then
+         goto continue
+      end
+      word = word:innerHtml()
+
+      local contributor = def:select(".contributor"):iter()()
+      local date = string.match(contributor:innerHtml(), ".*\\?</a>%s*(.*)\\?")
+      date = sws.Date(date, "%B %d, %Y"):format("%Y-%m-%d")
+
+      local meaning = def:select(".meaning"):iter()()
+      meaning = meaning:innerText():gsub("[\n\r]+", " ")
+
+      local example = def:select(".example"):iter()()
+      example = example:innerText():gsub("[\n\r]+", " ")
+
+      if word and date and meaning and example then
+         local record = sws.Record()
+         record:pushField(word)
+         record:pushField(defIndex)
+         record:pushField(date)
+         record:pushField(meaning)
+         record:pushField(example)
+         context:sendRecord(record)
+      end
+
+      ::continue::
+   end
+end
+```
+
+## CSV Record
+
+The Lua [Record](./lua_api_overview.html#class-record) class wraps a Rust
+[`csv::StringRecord`][csv-string-rec] struct. In `Lua` it can be instantiated through
+`sws.Record()`. Its `pushField(someString)` method should be used to add string fields
+to the record.
+
+It is possible to customize the underlying [CSV Writer][csv-writer] in `Lua` through the
+`sws.csvWriterConfig` table.
+
+| csv::WriterBuilder method    | Lua parameter | Example Lua value | Default Lua value |
+|------------------------------|---------------|-------------------|-------------------|
+| [delimiter][csv-delimiter]   | delimiter     | "\t"              | ","               |
+| [escape][csv-escape]         | escape        | ";"               | "\\""             |
+| [flexible][csv-flexible]     | flexible      | true              | false             |
+| [terminator][csv-terminator] | terminator    | CRLF              | { Any = "\n" }    |
+
+[csv-string-rec]: https://docs.rs/csv/latest/csv/struct.StringRecord.html
+[csv-writer]: https://docs.rs/csv/latest/csv/struct.Writer.html
+[csv-delimiter]: https://docs.rs/csv/latest/csv/struct.WriterBuilder.html#method.delimiter
+[csv-escape]: https://docs.rs/csv/latest/csv/struct.WriterBuilder.html#method.escape
+[csv-flexible]: https://docs.rs/csv/latest/csv/struct.WriterBuilder.html#method.flexible
+[csv-terminator]: https://docs.rs/csv/latest/csv/struct.WriterBuilder.html#method.terminator
+
+### Example
+
+```lua
+sws.csvWriterConfig = {
+   delimiter = "\t"
+}
+
+function scrapPage(page, context)
+    local record = sws.Record()
+    record:pushField("foo field")
+    record:pushField("bar field")
+    context:sendRecord(record)
+end
+```
diff --git a/doc/src/scrap_overview.md b/doc/src/scrap_overview.md
new file mode 100644
index 0000000..abeb57b
--- /dev/null
+++ b/doc/src/scrap_overview.md
@@ -0,0 +1,27 @@
+# Subcommand: scrap
+
+```text
+Scrap a single remote page or multiple local pages
+
+Usage: sws scrap [OPTIONS] --script <SCRIPT> <--url <URL>|--files <GLOB>>
+
+Options:
+  -s, --script <SCRIPT>            Path to the Lua script that defines scraping logic
+      --url <URL>                  A distant html page to scrap
+      --files <GLOB>               A glob pattern to select local files to scrap
+  -o, --output-file <OUTPUT_FILE>  Optional file that will contain scraped data, stdout otherwise
+      --append                     Append to output file
+      --truncate                   Truncate output file
+      --num-workers <NUM_WORKERS>  Set the number of CPU workers when scraping local files
+      --on-error <ON_ERROR>        Scrap error handling strategy when scraping local files [possible values: fail, skip-and-log]
+  -q, --quiet                      Don't output logs
+  -h, --help                       Print help information
+```
+
+The parameters `--url` and `--files` are mutually exclusive (only one can be specified).
+
+This subcommand is meant to either:
+
+* Quickly test a [Lua script](./lua_scraper.html) on a given URL (with `--url`)
+
+* Process HTML pages that have been previously stored on disk (with `--files`)
diff --git a/examples/urbandict.lua b/examples/urbandict.lua
index 0f29c47..4f517f7 100644
--- a/examples/urbandict.lua
+++ b/examples/urbandict.lua
@@ -12,18 +12,24 @@ end
 
 function scrapPage(page, context)
    for defIndex, def in page:select("section .definition"):enumerate() do
-      local word = def:select("h1 a.word"):iter()():innerHtml()
-      if string.find(word, "\t") then goto continue end
+      local word = def:select("h1 a.word"):iter()()
+      if not word then
+         word = def:select("h2 a.word"):iter()()
+      end
+      if not word then
+         goto continue
+      end
+      word = word:innerHtml()
 
       local contributor = def:select(".contributor"):iter()()
       local date = string.match(contributor:innerHtml(), ".*\\?</a>%s*(.*)\\?")
       date = sws.Date(date, "%B %d, %Y"):format("%Y-%m-%d")
 
       local meaning = def:select(".meaning"):iter()()
-      meaning = meaning:innerText():gsub("[\n\r]+", " "):gsub("\t+", "")
+      meaning = meaning:innerText():gsub("[\n\r]+", " ")
 
       local example = def:select(".example"):iter()()
-      example = example:innerText():gsub("[\n\r]+", " "):gsub("\t+", "")
+      example = example:innerText():gsub("[\n\r]+", " ")
 
       if word and date and meaning and example then
          local record = sws.Record()