Skip to content

Commit 116e494

Browse files
authored
Update root-dir recipe after relative root-dirs (#139)
* Update root-dir recipe after relative root-dirs also remove the suggestion to use root-dir and base-url together. * change tree diagram so text is upright instead of slanted slant came from the bash syntax highlighting mode.
1 parent 8f402b4 commit 116e494

1 file changed

Lines changed: 19 additions & 69 deletions

File tree

src/content/docs/recipes/root-dir.mdx

Lines changed: 19 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ These links start with `/`, meaning they're absolute paths.
2424
If the site is built in a `public` directory, the files will be in `public/about.html` and `public/docs/guide.html`. To check these links, you'd run:
2525

2626
```bash
27-
lychee --root-dir "$(pwd)/public" "**/*.html"
27+
lychee --root-dir ./public "**/*.html"
2828
```
2929

3030
lychee will look for:
@@ -46,18 +46,8 @@ Common scenarios:
4646
- Any project where links start with `/`
4747

4848
:::note
49-
`--root-dir` must be an absolute path. If you provide a relative path, lychee will error.
50-
51-
```bash
52-
# ✅ Good
53-
lychee --root-dir /home/user/project/public/
54-
55-
# ❌ Bad: will fail
56-
lychee --root-dir ./public/
57-
```
58-
59-
This is a conservative solution to prevent edge cases.
60-
If you have a use case for allowing relative root directories, please [open an issue](https://github.com/lycheeverse/lychee/issues).
49+
`--root-dir` can be an absolute or a relative path. Relative paths are taken
50+
relative to the current working directory.
6151
:::
6252

6353
## Examples
@@ -66,7 +56,7 @@ If you have a use case for allowing relative root directories, please [open an i
6656

6757
If you use Hugo, Jekyll, or similar tools, they often generate sites in a `public` directory:
6858

69-
```bash
59+
```text
7060
my-site/
7161
├── public/ # Generated files live here
7262
│ ├── about.html
@@ -79,26 +69,10 @@ my-site/
7969
To check the links:
8070

8171
```bash
82-
# Convert relative path to absolute first
83-
lychee --root-dir "$(pwd)/public" "public/**/*.html"
72+
lychee --root-dir public "public/**/*.html"
8473
```
8574

86-
For GitHub Actions, please replace `$(pwd)` with [`${{ github.workspace }}`](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context):
87-
88-
```yaml '${{ github.workspace }}'
89-
jobs:
90-
check-links:
91-
runs-on: ubuntu-latest
92-
steps:
93-
- uses: actions/checkout@v5
94-
- uses: lycheeverse/lychee-action@v2
95-
with:
96-
args: >-
97-
--verbose
98-
--no-progress
99-
--root-dir "${{ github.workspace }}/public"
100-
"public/**/*.html"
101-
```
75+
For GitHub Actions, the working directory can be accessed with [`${{ github.workspace }}`](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context).
10276

10377
### Documentation Site
10478

@@ -116,7 +90,7 @@ To check these links:
11690

11791
```bash
11892
# Assuming you're in the project root
119-
lychee --root-dir "$(pwd)" "docs/**/*.html"
93+
lychee --root-dir . "docs/**/*.html"
12094
```
12195

12296
## The Difference Between `--root-dir` and `--base-url`
@@ -125,52 +99,28 @@ These parameters serve different purposes:
12599

126100
- `--root-dir` is for finding files on your computer
127101
- Only affects links that start with `/`
128-
- Must be an absolute filesystem path
102+
- Must be a filesystem path
129103
- Used when checking local files
130104

131105
- [`--base-url`](/recipes/base-url) is for resolving URLs
132106
- Must be a URL (like `https://example.com/docs/`)
133107
- Used when checking how links will work once deployed
134-
- Affects relative links (like `./guide.html`)
135-
136-
### Using Both Together
137-
138-
Sometimes you need both:
139-
140-
```bash
141-
lychee \
142-
--root-dir "$(pwd)/public" \
143-
--base-url https://example.com/ \
144-
"public/**/*.html"
145-
```
146-
147-
This tells lychee:
148-
149-
1. Look for `/`-prefixed files in `./public/`
150-
2. Resolve relative links against `https://example.com/`
108+
- Affects all relative links (like `./guide.html`)
151109

152110
## Troubleshooting
153111

154112
If your links aren't being found:
155113

156-
1. Make sure you're using an absolute path:
114+
1. Check that the files exist in the location you expect:
157115

158-
```bash
159-
# Get absolute path in bash
160-
full_path="$(pwd)/public"
161-
lychee --root-dir "$full_path" "**/*.html"
162-
```
116+
```bash
117+
# Example debugging steps
118+
ls -la ./public/about.html
119+
ls -la ./public/docs/guide.html
120+
```
163121

164-
2. Check that the files exist in the location you expect:
122+
2. Use `--verbose` to see how lychee is resolving paths:
165123

166-
```bash
167-
# Example debugging steps
168-
ls -la ./public/about.html
169-
ls -la ./public/docs/guide.html
170-
```
171-
172-
3. Use `--verbose` to see how lychee is resolving paths:
173-
174-
```bash
175-
lychee --root-dir "$(pwd)/public" --verbose "**/*.html"
176-
```
124+
```bash
125+
lychee --root-dir "$(pwd)/public" --verbose "**/*.html"
126+
```

0 commit comments

Comments
 (0)