Tweaks for docs and add howto

Signed-off-by: Christoph Rueger <[email protected]>

small rearrangments to sidebar

- pulling content higher up which might be interesting for new users
- merge sections "Introduction" and "Installation" into "Getting started" and add FAQ too

clear caches on startup of jekyll server

helps e.g. when making changes to sidebar
Signed-off-by: Christoph Rueger <[email protected]>

adding summary sentence to front page

Signed-off-by: Christoph Rueger <[email protected]>

improve manual

fix link

Signed-off-by: Christoph <[email protected]>

docs/README.md

@@ -20,3 +20,28 @@ using [GitHub Pages](https://help.github.com/articles/what-are-github-pages/).
 # Build it
 ./build.sh
 ```
+
+## Setup local docs development environment (MacOS)
+
+If you get an error like `activesupport-7.0.7.2 requires ruby version >= 2.7.0, which is incompatible with the current version, ruby 2.6.10p210` when executing `./run.sh` then consider doing the following:
+
+- Install rbenv Ruby Version manager https://github.com/rbenv/rbenv e.g. via brew
+- and then use it to install and use e.g. ruby 3.1.2
+
+```
+brew install rbenv
+rbenv init
+rbenv install 3.1.2
+rbenv global 3.1.2
+./run.sh
+```
+
+After a successfull start of `./run.sh` you see this:
+
+```
+Server address: http://127.0.0.1:4000
+Server running... press ctrl-c to stop.
+```
+
+Open http://127.0.0.1:4000 in your browser to see the result while developing. 
+The server does support hot-reload so you should see changes to `.md` files immediately without restart (there are a few exceptions). Checkout the [jekyll-docs](https://jekyllrb.com/docs/pages/) to get more into the details and features.

docs/_chapters/120-install.md

@@ -47,7 +47,7 @@ The manual is also on [github][5]. If you see an improvement, do not hesitate to
 
 If you're behind a firewall that requires proxies or you use repositories that require authentication see [-connection-settings][6].
 
-[1]: https://brew.sh/
+[1]: https://formulae.brew.sh/formula/bnd
 [3]: https://github.com/bndtools/bnd
 [4]: https://bndtools.jfrog.io/bndtools/libs-snapshot
 [5]: https://github.com/bndtools/bnd/tree/master/docs

docs/_data/sidebar.yml

@@ -1,16 +1,13 @@
 nav:
-  - title: Introduction
-    subfolderitems:
-      - url: /chapters/110-introduction.html
-  - title: Installation
-    subfolderitems:
-      - url: /chapters/120-install.html
   - title: Getting Started
     subfolderitems:
+      - url: /chapters/120-install.html
       - url: /chapters/123-tour-workspace.html
       - url: /chapters/125-tour-features.html
+      - url: /chapters/920-faq.html
   - title: Concepts and Practices
     subfolderitems:
+      - url: /chapters/110-introduction.html
       - url: /chapters/130-concepts.html
       - url: /chapters/140-best-practices.html
   - title: Build and Development
@@ -62,4 +59,3 @@ nav:
       - url: /chapters/880-settings.html
       - url: /chapters/900-errors.html
       - url: /chapters/910-warnings.html
-      - url: /chapters/920-faq.html

docs/_layouts/front.html

@@ -11,6 +11,16 @@
 		<img span=12 src="{{ '/img/front-page.png' | prepend:site.baseurl }}">
 	</div>
 
+	<div class=container12>
+		<h4 style="text-align: center">Bnd is a tooling suite for building OSGi bundles.
+			Its primary function is generating OSGi meta data by analyzing Java classes.
+			<br />
+			There are plugins for popular tools like Eclipse, Maven and Gradle.
+		</h4>
+	</div>
+
+
+
 	<ul class=container12>
 		<li span=4>
 			<h1>What is bnd?</h1>

docs/run.sh

@@ -3,5 +3,6 @@ set -ev
 
 export BUNDLE_GEMFILE=$PWD/Gemfile
 bundle install --jobs=3 --retry=3
+bundle exec jekyll clean
 bundle exec jekyll serve -w --incremental