Merge pull request #6246 from bndtools/chrisrueger-docs-tweaks

Tweaks for docs
bndtools · Aug 28, 2024 · cb6f758 · cb6f758
2 parents 38272cf + 7d7e5a2
commit cb6f758
Show file tree

Hide file tree

Showing 5 changed files with 40 additions and 8 deletions.
diff --git a/docs/README.md b/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.
diff --git a/docs/_chapters/120-install.md b/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

diff --git a/docs/_data/sidebar.yml b/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
diff --git a/docs/_layouts/front.html b/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>

diff --git a/docs/run.sh b/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