Skip to content

Commit b15c7b7

Browse files
committed
docs: improve docs
1 parent 37f4c21 commit b15c7b7

File tree

15 files changed

+112
-61
lines changed

15 files changed

+112
-61
lines changed

README.md

Lines changed: 22 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -42,16 +42,16 @@ https://dir-demo.adriansoftware.de
4242
## Features
4343
- **Download counter** for all files
4444
- Secure by default. **Read-only** access
45-
- Extremly **fast** file serving through **nginx**
45+
- Extremely **fast** file serving through **nginx**
4646
- **README** markdown rendering support
4747
- **JSON API** for programmatic access
4848
- **Batch download** of files and folders in a zip archive
49-
- **file integrity** check with **hashes**
50-
- **custom description** and **labels** for files and folders
49+
- **File integrity** checks with **hashes**
50+
- **Custom descriptions** and **labels** for files and folders
5151
- **Search** and **sorting** built-in
5252
- **Password** protection
5353
- **Hide** files and folders
54-
- Light and **Darkmode**
54+
- Light and **Dark mode**
5555
- File **icons**
5656
- Many **Themes** available
5757
- **Clean URLs** equivalent to file system paths
@@ -65,3 +65,21 @@ https://dir-demo.adriansoftware.de
6565
- Track request timing
6666
- **arm64** support
6767
- Works **without JavaScript** enabled
68+
69+
## Quick start (Docker)
70+
71+
Serve a local folder read-only at http://localhost:8080:
72+
73+
```bash
74+
docker run -d \
75+
--name dir-browser \
76+
-p 8080:80 \
77+
-v /my/local/folder:/var/www/html/public:ro \
78+
-v rdb:/var/lib/redis/ \
79+
adrianschubek/dir-browser:latest
80+
```
81+
82+
## Documentation
83+
84+
- Docs: https://dir.adriansoftware.de
85+
- Demo: https://dir-demo.adriansoftware.de

docs/README.md

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,22 @@
11
# Website
22

3-
This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
3+
This documentation site is built with [Docusaurus](https://docusaurus.io/).
4+
5+
Prerequisites:
6+
- Node.js (see the required version in `docs/package.json`)
7+
- A package manager (this repo uses Yarn in the examples)
48

59
### Installation
610

711
```
12+
$ cd docs
813
$ yarn
914
```
1015

1116
### Local Development
1217

1318
```
19+
$ cd docs
1420
$ yarn start
1521
```
1622

@@ -19,6 +25,7 @@ This command starts a local development server and opens up a browser window. Mo
1925
### Build
2026

2127
```
28+
$ cd docs
2229
$ yarn build
2330
```
2431

docs/docs/advanced/redis.md

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
Redis is used to store the [download counter](./../configuration/download-count.md) data. If the download counter is disabled, Redis will not be loaded/started at all.
44

5+
Counters are stored with the request path as key (relative to the mounted folder), for example `/reports/2024.pdf`.
6+
57
### Access
68

79
Sometimes it is useful to access the Redis instance directly e.g. for resetting a counter. This can be done using the `redis-cli` tool inside the container.
@@ -18,6 +20,8 @@ redis-cli
1820
See https://redis.io/docs/latest/commands/ for a list of available commands.
1921

2022
### List all stored counters
23+
For small datasets you can use `KEYS`, but note that it can be slow on large databases.
24+
2125
```bash title="$> KEYS *"
2226
...
2327
25) "/src/index.php"
@@ -33,10 +37,10 @@ See https://redis.io/docs/latest/commands/ for a list of available commands.
3337
...
3438
```
3539
### Read a counter
36-
```bash title="$> GET /src/index.php"
40+
```bash title="$> GET /example.txt"
3741
123
3842
```
3943
### Reset/Modify a counter
40-
```bash title="$> SET /src/index.php 0"
44+
```bash title="$> SET /example.txt 0"
4145
OK
4246
```

docs/docs/configuration/attribution.md.x

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,4 @@ sidebar_position: 5
44

55
# Attribution
66

7-
You can hide the attribution by setting the environment variable `HIDE_ATTRIBUTION` to `true`.
7+
dir-browser includes a small footer ("Powered by dir-browser") that links back to the project documentation and shows the running version. You can hide it by setting the environment variable `HIDE_ATTRIBUTION` to `true`.

docs/docs/configuration/i18n.md

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,9 @@
11
---
22
sidebar_position: 3
33
---
4-
# Format
4+
# Date & Time
55

6-
## Date & Time
7-
8-
The date and time format for files/folders displayed in the file tree.
6+
Controls how file and folder timestamps are displayed in the file list.
97

108
<!-- table with options: relative, local, utc -->
119
| Value | Description |
@@ -14,9 +12,9 @@ The date and time format for files/folders displayed in the file tree.
1412
| `utc` | UTC time (e.g. `2021-08-01 12:32:55 UTC`) |
1513
| `relative` (Default) | Relative time based on user's localized date format (e.g. `2 days ago` in English) |
1614

17-
All times will be displayed in the user's local timezone.
15+
Times are displayed in the user's local timezone.
1816

19-
When using the `relative` format you can override the language by setting the environment variable `DATE_FORMAT_RELATIVE_LANG` (e.g. `DATE_FORMAT_RELATIVE_LANG=de` will output relative times in German). By default it uses the locale of the user.
17+
When using the `relative` format you can override the language used for phrases like “2 days ago” by setting `DATE_FORMAT_RELATIVE_LANG` (for example `de`). By default it uses the browser/user locale.
2018

2119

2220
import EnvConfig from '@site/src/components/EnvConfig';

docs/docs/configuration/ignore.mdx

Lines changed: 17 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -10,22 +10,26 @@ In contrast to using [metadata](./metadata.md) the file or folder is completely
1010

1111
### Ignore patterns
1212

13-
Hide specific files or folders by defining an ignore pattern using regular expressions.
13+
Hide specific files or folders by defining ignore patterns as regular expressions.
1414

15-
It uses [preg_match](https://www.php.net/manual/en/function.preg-match.php) to match the file path. Pattern matching is case insensitive.
16-
If a match is found the file/folder will be hidden.
15+
Internally, each pattern is evaluated against the full file path using [preg_match](https://www.php.net/manual/en/function.preg-match.php). Matching is case-insensitive.
16+
If any pattern matches, the file/folder will be hidden.
17+
18+
Notes:
19+
- The path always starts with `/`, which is the mounted folder.
20+
- Patterns are wrapped as `#<pattern>#im` internally. Avoid using `#` in patterns.
1721
The path always starts with a `/`, which is the mounted folder.
1822

1923
#### Examples
2024

21-
| Pattern | Description | Hidden | Not Hidden |
22-
| ------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------- | ---------------------------------------------- |
23-
| `/\..*` | Hide everything starting with a dot `.` like `.env`, `.git`... | `/foo/.bar`, `/.foo/bar` | `/foo/bar` |
24-
| `^/foo/.*\.txt$` | Hide everything in the folder `/foo` ending with `.txt` | `/foo/abc.txt` | `/foo/abc.md`, `/bar/foo/abc.txt` |
25-
| `^/node_modules/` | Hide the folder `/node_modules` and its content | `/node_modules` | `/foo/node_modules` |
26-
| `/node_modules/` | Hide the folder `node_modules` and its content at any level | `/node_modules`, `/foo/node_modules` | `/node_modules_123` |
27-
| `^/reports/2023.*\.pdf` | Hide all pdf files in the folder `/reports` starting with `2023` | `/reports/2023-01.pdf`, `/reports/2023-02.pdf` | `/reports/2022-01.pdf`, `/reports/2023-01.txt` |
28-
| `^/secret/.*\.(jpg\|png)$` | Hide all images deep inside the folder `/secret` | `/secret/foo.jpg`, `/secret/bar/abc.png` | `/secret/foo.png.txt`, `/foo/secret/abc.png` |
25+
| Pattern | Description | Hidden | Not Hidden |
26+
| --- | --- | --- | --- |
27+
| `/\..*` | Hide dotfiles like `.env`, `.git` at any depth | `/foo/.bar`, `/.foo/bar` | `/foo/bar` |
28+
| `^/foo/.*\.txt$` | Hide everything in `/foo` ending with `.txt` | `/foo/abc.txt` | `/foo/abc.md`, `/bar/foo/abc.txt` |
29+
| `^/node_modules/` | Hide `/node_modules` only at the root | `/node_modules` | `/foo/node_modules` |
30+
| `/node_modules/` | Hide `node_modules` at any depth | `/node_modules`, `/foo/node_modules` | `/node_modules_123` |
31+
| `^/reports/2023.*\.pdf$` | Hide PDFs in `/reports` starting with `2023` | `/reports/2023-01.pdf` | `/reports/2022-01.pdf`, `/reports/2023-01.txt` |
32+
| `^/secret/.*\.(jpg\|png)$` | Hide images anywhere under `/secret` | `/secret/foo.jpg`, `/secret/bar/abc.png` | `/secret/foo.png.txt`, `/foo/secret/abc.png` |
2933

3034

3135
You can hide some files and folders by setting the environment variable `IGNORE` to a pattern. By default everything is shown.
@@ -37,7 +41,7 @@ Patterns are matched against the file name and every parent folder name **indivi
3741

3842
For example if you have a file `foo/bar/secret.txt`. This path will be split into an array `['foo', 'bar', 'secret.txt']` and each part will be matched against the pattern. If at any point the pattern matches the name, it will be hidden.
3943

40-
Usecase: Hide everything starting with a dot <kbd>.</kbd> using a `.*` pattern globally at any nesting level. This will hide `/foo/bar/.foobar`, `/.baz`, `/foo/.secret/bar` etc.
44+
Use case: Hide everything starting with a dot <kbd>.</kbd> using a `.*` pattern globally at any nesting level. This will hide `/foo/bar/.foobar`, `/.baz`, `/foo/.secret/bar` etc.
4145

4246
It uses [fnmatch](https://www.php.net/manual/en/function.fnmatch.php) to match the pattern.
4347

@@ -68,7 +72,7 @@ It uses [fnmatch](https://www.php.net/manual/en/function.fnmatch.php) to match t
6872

6973
### Multiple patterns
7074

71-
You can specify multiple patterns and seperate them using a `;`. If any of the patterns matches, the file or folder will be hidden.
75+
You can specify multiple patterns and separate them using `;`. If any pattern matches, the file or folder will be hidden.
7276

7377
import EnvConfig from "@site/src/components/EnvConfig";
7478

docs/docs/configuration/language.md.todo

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,6 @@ sidebar_position: 4
44

55
# Language
66

7-
Available Languages: `en` (English), `de` (Deutsch)
7+
dir-browser does not currently provide full UI translations via a `LANGUAGE` environment variable.
88

9-
By default the language is set to `en`. You can change it by setting the `LANGUAGE` environment variable.
10-
11-
```
12-
docker run -d -p 8080:80 -v /my/local/folder:/var/www/html/public:ro -e LANGUAGE=de -v redissave:/var/lib/redis/ -it adrianschubek/dir-browser
13-
```
9+
If you want to influence language output, the main supported knob is for **relative time strings** (for example “2 days ago”). See [Date & Time](./i18n.md) and use `DATE_FORMAT_RELATIVE_LANG`.

docs/docs/configuration/readme.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,4 +17,4 @@ By default unsafe HTML inside markdown (such as `<script>`) will be escaped. You
1717

1818
import EnvConfig from '@site/src/components/EnvConfig';
1919

20-
<EnvConfig name="README_RENDER|README_NAME|README_FIRST|ALLOW_RAW_HTML|README_META" init="true|readme.md;readme.txt;readme.html;readme;read.me;read\ me;liesmich.md;liesmich.txt;liesmich;lies\ mich;index.html;index.htm;index.txt;license|false|false|true" values="true,false|<string>|true,false|true,false|true,false" versions="1.1|3.2|3.2|1.1|3.5" desc="|The case-insensitive file names seperated by a semicolon which should be rendered|Render the readme above the file tree instead of below it.||Renders a .dbmeta.md file if it exists" />
20+
<EnvConfig name="README_RENDER|README_NAME|README_FIRST|ALLOW_RAW_HTML|README_META" init="true|readme.md;readme.txt;readme.html;readme;read.me;read\ me;liesmich.md;liesmich.txt;liesmich;lies\ mich;index.html;index.htm;index.txt;license|false|false|true" values="true,false|<string>|true,false|true,false|true,false" versions="1.1|3.2|3.2|1.1|3.5" desc="|The case-insensitive file names separated by a semicolon which should be rendered|Render the readme above the file tree instead of below it.||Renders a .dbmeta.md file if it exists" />

docs/docs/configuration/search.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,4 +42,4 @@ This engine is the most powerful but slower than the glob engine. It is useful f
4242
4343
import EnvConfig from '@site/src/components/EnvConfig';
4444

45-
<EnvConfig name="SEARCH|SEARCH_ENGINE|SEARCH_MAX_DEPTH|SEARCH_MAX_RESULTS|REVERSE_SORT" init="true|s,g|25|100|false" values="true,false|s,g,r|integer|integer|true,false" versions="3.7|3.8|3.7|3.7|1.0" desc="Enables or disables the search functionality|s=simple, g=glob, r=regex. Multiple values seperated using commas.|Maximum recursive search depth (simple and regex engine only)|Maximum number of results in a single request|By default files and folders are sorted by name using natural sort."/>
45+
<EnvConfig name="SEARCH|SEARCH_ENGINE|SEARCH_MAX_DEPTH|SEARCH_MAX_RESULTS|REVERSE_SORT" init="true|s,g|25|100|false" values="true,false|s,g,r|integer|integer|true,false" versions="3.7|3.8|3.7|3.7|1.0" desc="Enables or disables the search functionality|s=simple, g=glob, r=regex. Multiple values separated using commas.|Maximum recursive search depth (simple and regex engine only)|Maximum number of results in a single request|By default files and folders are sorted by name using natural sort."/>

docs/docs/development/development.md

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,18 +4,18 @@ sidebar_position: 2
44

55
# Development
66

7-
Contributions are welcome. If you would like to contribute, please follow the steps below.
7+
Contributions are welcome. To run dir-browser locally from source:
88

9-
1. Clone the repository https://github.com/adrianschubek/dir-browser
10-
2. Run the following command in the project folder. Be sure to replace `/some/local/folder` with a valid path to a folder.
9+
1. Clone the repository: https://github.com/adrianschubek/dir-browser
10+
2. Build and run the image from the project root. Replace `/some/local/folder` with a local folder you want to serve.
1111

1212
```
1313
docker run --rm --name dir -p 8080:80 -v /some/local/folder:/var/www/html/public:ro -v redissave:/var/lib/redis/ -it $(docker build -q -f Dockerfile .)
1414
```
1515
It may take a few minutes to build the image.
1616

17-
3. Open http://localhost:8080 in your browser
17+
3. Open http://localhost:8080
1818

19-
If you make any changes to the code, you have to rerun the docker command.
19+
After making code changes, rebuild and re-run the container.
2020

21-
This project uses special syntax from the [utpp](https://github.com/adrianschubek/utpp) project, a CLI tool to pre-process and execute JavScript inside configuration files at startup. It's created by the same author as this project. If you would like to learn more about it, please visit the [documentation](https://utpp.adriansoftware.de/).
21+
This project uses special syntax from [utpp](https://github.com/adrianschubek/utpp), a CLI tool that preprocesses templates and can execute JavaScript at build time. If you want to learn more, see https://utpp.adriansoftware.de/.

0 commit comments

Comments
 (0)