https://github.com/ff4j/docs

Building a real documentation for FF4j with MKDocs and Materials
https://github.com/ff4j/docs

Last synced: about 1 month ago
JSON representation

Building a real documentation for FF4j with MKDocs and Materials

• Host: GitHub
• URL: https://github.com/ff4j/docs
• Owner: ff4j
• Created: 2022-05-16T12:27:46.000Z (over 2 years ago)
• Default Branch: main
• Last Pushed: 2023-08-26T17:06:56.000Z (over 1 year ago)
• Last Synced: 2024-03-27T07:21:57.930Z (9 months ago)
• Size: 7.39 MB
• Stars: 0
• Watchers: 4
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        
# FF4j Documentation

 [![Awesome](https://awesome.re/badge-flat.svg)](https://awesome.re)

Static site is generated on branch `gh-pages` using a github actions.

## Run the website locally

### 1. Installation

```bash

python3 -m pip install --upgrade pip     # install pip

python3 -m pip install mkdocs            # install mkdocs 

python3 -m pip install mkdocs-material   # install material theme

#python3 -m pip install https://github.com/bmcorser/fontawesome-markdown/archive/master.zip   # install font-awesome

python3 -m pip install mkdocs-git-revision-date-plugin # install git revision date

python3 -m pip install mkdocs-video # install git revision date

```

Or use this one-liner :) 

```

python3 -m pip install --upgrade pip && python3 -m pip install mkdocs mkdocs-material https://github.com/bmcorser/fontawesome-markdown/archive/master.zip mkdocs-git-revision-date-plugin

```

### 2. Run

```

mkdocs serve

```

You should be able to access it on http://localhost:8000

**Known Issue:**

If you get an `mkdocs not found error`, launch it this way: 

```

python3 -m mkdocs serve

```

### 3. Instructions

#### Images

**Caution**: when running locally, the site is served at `http://127.0.0.1:8000/pages/[...]`

while when deployed, it is at `https://ff4j.github.io/docs/pages/[...]`.

This means that if you use "absolute" image URLs such as `/img/ETC ETC` one will work

and the other won't. Unfortunately you have to always use relative paths and climb up

the ladder with `../../../../img/ETC ETC` !

In other words, **if you use `"/img/tile-java.png"` it will render OK locally and

then screw up once deployed**.

Also, when calculating the number of `..` to insert, count ONE LESS for `index.md` files as opposed to all other `md` files:

`index.md` renders as the page for the path containing it (`a/b/c/index.md` renders the URL `a/b/c`).

For company logo files, SVG format is preferred to PNG.