Redesign website

* Bump up Bootstrap to v5.3.1, Bootstrap Icon to v1.10.5.
* Use autoComplete.js to drop dependency on jQuery and typeahead.js.
* Support dark mode.
* New svg logo and icon with responsive color mode support.
* Normalize section ids to lower kebab-case for easiness of linking.
* Use relative paths for links for local development (--root /output).
* Various markup cleanups and accessibility improvements.

.github/workflows/website.yml

@@ -20,7 +20,7 @@ jobs:
       - name: Setup Python
         uses: actions/setup-python@v4
         with:
-          python-version: '3.10'
+          python-version: '3.11'
           cache: pipenv
       - name: Install pipenv
         run: pip install pipenv

Makefile.am

@@ -197,14 +197,10 @@ endif
 
 ### Packaging
 
-docs/site.yml: configure.ac
-	sed 's/^jq_version: .*/jq_version: "$(VERSION)"/' $@ > $@.new
-	mv $@.new $@
-
 install-binaries: $(BUILT_SOURCES)
 	$(MAKE) $(AM_MAKEFLAGS) install-exec
 
-DOC_FILES = docs/content docs/public docs/templates docs/site.yml       \
+DOC_FILES = docs/content docs/public docs/templates                     \
         docs/Pipfile docs/Pipfile.lock docs/build_manpage.py            \
         docs/build_mantests.py docs/build_website.py docs/README.md     \
         docs/validate_manual_schema.py docs/manual_schema.yml

docs/README.md

@@ -11,16 +11,16 @@ need `python3` and `pipenv`. You can install `pipenv` like so:
 
 Though, you may need to say `pip3` instead, depending on your system. Once
 you have `pipenv` installed, you can install the dependencies by running
-`pipenv sync` from the `docs` directory.
+`pipenv sync` from the `docs/` directory.
 
 Also, you may need to run `virtualenv -p /usr/bin/python3 venv/` and
 then `source venv/bin/activate`, and only then `pipenv sync`.
 
 Once this is done, rerun `./configure` in the jq root directory and then
-the Makefile will be able to generate the jq manpage.  You can also just
-run `pipenv run build_manpage.py` in the `docs` directory to build the
-`jq.1` page manually, and `pipenv run build_mantests.py` to build the
-contents of `tests/man.test` and `tests/manonig.test`.
+the `Makefile` will be able to generate the jq manpage.  You can just run
+`make jq.1` to build the manpage manually, and `make tests/man.test` to
+update the manual tests.
 
-To build the website, run `pipenv run ./build_website.py` from inside
-the `docs` directory.
+To build the website, run `pipenv run python3 build_website.py --root /output`
+in the `docs/` directory. To serve them locally, you can run
+`python3 -m http.server`.

docs/build_website.py

@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+import argparse
 import glob
 import itertools
 from jinja2 import Environment, FileSystemLoader, select_autoescape, pass_context
@@ -10,6 +11,10 @@
 import shutil
 import yaml
 
+parser = argparse.ArgumentParser()
+parser.add_argument('--root', default='/jq')
+args = parser.parse_args()
+
 env = Environment(
     loader=FileSystemLoader('templates'),
     autoescape=select_autoescape(['html.j2']),
@@ -21,40 +26,51 @@ def load_yml_file(fn):
         return yaml.safe_load(f)
 
 
+env.globals['url'] = 'https://jqlang.github.io/jq'
+env.globals['root'] = args.root
+
 env.filters['search_id'] = lambda input: input.replace(r'`', '')
-env.filters['section_id'] = lambda input: re.sub(r"[^a-zA-Z0-9_]", '', input)
-env.filters['entry_id'] = lambda input: re.sub(r"[ `]", '', input)
+env.filters['section_id'] = lambda input: re.sub(
+    r'[^-a-zA-Z0-9_]', '', input.replace(' ', '-')).lower()
+env.filters['entry_id'] = lambda input: re.sub(
+    r'^(split|first-last-nth)$',
+    r'\1' + ('-1' if ';' not in input else '-2'),  # avoid id conflict
+    re.sub(
+        r'\b([^-]+)(?:-\1)+\b',
+        r'\1',  # e.g. range-range-range -> range
+        re.sub(r' ?/ ?|,? ', '-',
+               re.sub(r'[`;]|: .*|\(.*?\)| \[.+\]', '', input)))).lower()
 env.filters['markdownify'] = lambda input: Markup(markdown(input))
-env.filters['no_paragraph'] = lambda input: Markup(re.sub(r"</?p>", '', input))
+env.filters['no_paragraph'] = lambda input: Markup(re.sub(r'</?p>', '', input))
 
 env.globals['unique_id'] = pass_context(
     lambda ctx: str(next(ctx['unique_ctr'])))
 
-env.globals.update(load_yml_file('site.yml'))
 
-env.globals['navigation'] = ['tutorial', 'download', 'manual']
+def raise_handler(message):
+    raise Exception(message)
+
+
+env.globals['raise'] = raise_handler
 
 
-def generate_file(env, fname='content/1.tutorial/default.yml'):
+def generate_file(env, fname):
     path, base = os.path.split(fname)
     path = os.path.relpath(path, 'content')
     if path == '.':
         path = ''
-        slug = 'index'
         permalink = ''
     else:
-        slug = os.path.basename(path)
         permalink = path + '/'
 
     output_dir = os.path.join('output', path)
     output_path = os.path.join(output_dir, 'index.html')
 
-    template_name = re.sub(r".yml$", '.html.j2', base)
+    template_name = re.sub(r'.yml$', '.html.j2', base)
 
     ctx = load_yml_file(fname)
     ctx.update(unique_ctr=itertools.count(1),
                permalink=permalink,
-               slug=slug,
                navitem=path)
     os.makedirs(output_dir, exist_ok=True)
     env.get_template(template_name).stream(ctx).dump(output_path,
@@ -72,6 +88,7 @@ def copy_public_files(root=''):
             shutil.copyfile(f.path, dst)
 
 
+os.makedirs('output', exist_ok=True)
 copy_public_files()
 
 for fn in glob.glob('content/**/*.yml', recursive=True):

docs/content/download/default.yml

@@ -196,9 +196,9 @@ body:
       #### Building the documentation
 
       jq's documentation is compiled into static HTML using Python.
-      To build the docs, run `pipenv run python3 build_website.py` from
-      the docs/ subdirectory. To serve them locally, you can run
-      `python3 -m SimpleHTTPServer`. You'll need a few Python dependencies,
+      To build the docs, run `pipenv run python3 build_website.py --root /output`
+      in the `docs/` directory. To serve them locally, you can run
+      `python3 -m http.server`. You'll need a few Python dependencies,
       which can be installed by following the instructions in `docs/README.md`.
 
       The man page is built by `make jq.1`, or just `make`, also from

docs/content/index.yml

@@ -24,7 +24,7 @@ body3: |
 
 tail: |
 
-  Go read the [tutorial](/jq/tutorial/) for more, or the [manual](/jq/manual/)
+  Go read the [tutorial](./tutorial/) for more, or the [manual](./manual/)
   for *way* more.
 
   Have a question related to jq? You can seek answers on [Stack Overflow](https://stackoverflow.com/)
@@ -34,7 +34,7 @@ tail: |
 news:
   - date: 1 November 2018
     body: |
-      jq 1.6 released. See installation options on the [download](/jq/download/)
+      jq 1.6 released. See installation options on the [download](./download/)
       page, and the [release notes](https://github.com/jqlang/jq/releases/tag/jq-1.6)
       for details.
 
@@ -44,7 +44,7 @@ news:
       jq 1.5 released, including new datetime, math, and regexp functions,
       try/catch syntax, array and object destructuring, a streaming parser,
       and a module system. See installation options on the
-      [download](/jq/download/) page, and the
+      [download](./download/) page, and the
       [release notes](https://github.com/jqlang/jq/releases/tag/jq-1.5)
       for details.
 
@@ -63,7 +63,7 @@ news:
   - date: 09 June 2014
     body: |
 
-      jq 1.4 (finally) released! Get it on the [download](/jq/download/) page.
+      jq 1.4 (finally) released! Get it on the [download](./download/) page.
 
   - date: 19 May 2013
     body: |

docs/content/manual/manual.yml

@@ -3,9 +3,8 @@ headline: jq Manual (development version)
 
 history: |
 
-  *For released versions, see [jq 1.6](/jq/manual/v1.6),
-  [jq 1.5](/jq/manual/v1.5),  [jq 1.4](/jq/manual/v1.4)
-  or [jq 1.3](/jq/manual/v1.3).*
+  *For released versions, see [jq 1.6](./v1.6/), [jq 1.5](./v1.5/),
+  [jq 1.4](./v1.4/) or [jq 1.3](./v1.3/).*
 
 body: |
 

docs/content/manual/v1.3/manual.yml

@@ -4,7 +4,7 @@ headline: jq 1.3 Manual
 history: |
 
   *The manual for the development version of jq can be found
-  [here](/jq/manual).*
+  [here](../).*
 
 body: |
 

docs/content/manual/v1.4/manual.yml

@@ -4,7 +4,7 @@ headline: jq 1.4 Manual
 history: |
 
   *The manual for the development version of jq can be found
-  [here](/jq/manual).*
+  [here](../).*
 
 body: |
 

docs/content/manual/v1.5/manual.yml

@@ -4,7 +4,7 @@ headline: jq 1.5 Manual
 history: |
 
   *The manual for the development version of jq can be found
-  [here](/jq/manual).*
+  [here](../).*
 
 body: |
 

docs/content/manual/v1.6/manual.yml

@@ -4,7 +4,7 @@ headline: jq 1.6 Manual
 history: |
 
   *The manual for the development version of jq can be found
-  [here](/jq/manual).*
+  [here](../).*
 
 body: |