Skip to content

Commit 8a7aac4

Browse files
johnnyfivepijohnnyfivepi
committed
Adding section with steps on how to run the site locally (for anyone who wants to edit or contribute to the guide)
1 parent d5f139e commit 8a7aac4

File tree

5 files changed

+345
-7
lines changed

5 files changed

+345
-7
lines changed

‎README.md‎

Lines changed: 76 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -84,8 +84,77 @@ Suggestions, improvements, or ideas? I'd love your input!
8484
- Friendly contributions are always welcome — even typo fixes!
8585

8686
---
87+
<a id="run-this-site-locally"></a>
8788

88-
## 🧩 Optional: Run This Site Locally
89+
## 🧩 Run this site locally (preview before pushing)
90+
91+
> 💡 **Note:** Run all commands from your local terminal (VS Code → View → Terminal).
92+
93+
You can preview this GitHub Pages site locally using **Jekyll** — the same engine GitHub uses — so you don’t have to commit every tiny CSS tweak like I did. 🫠
94+
95+
### 🔧 Option A: Ruby + Bundler (recommended)
96+
97+
1. **Install Bundler** (macOS/Linux):
98+
99+
```bash
100+
gem install bundler
101+
```
102+
103+
2. **Add a Gemfile** in the `docs/` folder:
104+
105+
```ruby
106+
# docs/Gemfile
107+
source "https://rubygems.org"
108+
109+
gem "github-pages", group: :jekyll_plugins
110+
gem "webrick" # required on Ruby 3+
111+
```
112+
113+
3. **Install and serve**:
114+
115+
```bash
116+
cd docs
117+
bundle install
118+
bundle exec jekyll serve --livereload
119+
```
120+
121+
4. **Open the site**:
122+
123+
- http://127.0.0.1:4000
124+
125+
> Tip: leave the server running — edits to Markdown, CSS, and images will auto-reload.
126+
127+
---
128+
129+
### 🐋 Option B: Docker (no local Ruby needed)
130+
131+
1. From the **repo root**, run:
132+
133+
```bash
134+
docker run --rm -it -p 4000:4000 -v "$PWD":/srv/jekyll jekyll/jekyll \
135+
jekyll serve --source docs --livereload
136+
```
137+
138+
2. **Open the site**:
139+
140+
- http://127.0.0.1:4000
141+
142+
---
143+
144+
### 🧹 Troubleshooting running the site locally
145+
146+
- **Could not locate Gemfile**
147+
Make sure the file exists at `docs/Gemfile` and you ran commands from `docs/`.
148+
149+
- **CSS not updating**
150+
If the browser is caching, hard-reload or open a private window.
151+
If needed, stop and restart the Jekyll server.
152+
153+
- **Port already in use**
154+
Try a different port:
155+
```bash
156+
bundle exec jekyll serve --livereload --port 4001
157+
```
89158

90159
---
91160

@@ -494,7 +563,7 @@ To enable **UDP GRO forwarding** permanently:
494563
rx-udp-gro-forwarding: on
495564
```
496565
497-
Credit to [@brkdncr](https://gitlab.com/brkdncr) for surfacing this tip and sharing a reproducible service example ([Issue #1](https://github.com/johnnyfivepi/tailscale-on-raspberry-pi/issues/1)).
566+
Credit to [@brkdncr](https://github.com/brkdncr) for surfacing this tip and sharing a reproducible service example ([Issue #1](https://github.com/johnnyfivepi/tailscale-on-raspberry-pi/issues/1)).
498567
499568
---
500569
@@ -512,6 +581,11 @@ Self-hosting a VPN (and setting up an exit node) with Tailscale on a Raspberry P
512581

513582
---
514583

584+
**Maintainer note:** Want to edit or contribute to this guide?
585+
See [🧩 Run this site locally](#run-this-site-locally) for setup instructions.
586+
587+
---
588+
515589
### Support this project
516590

517591
Thank you, reader, for following along with me!

‎docs/.jekyll-metadata‎

785 Bytes
Binary file not shown.

‎docs/_site/index.html‎

Lines changed: 105 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -25,9 +25,9 @@
2525
<meta name="viewport" content="width=device-width, initial-scale=1">
2626
<meta name="theme-color" content="#157878">
2727
<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
28-
<link rel="stylesheet" href="/assets/css/style.css?v=02f67b8d60b771c625d1b67fd8130dff34e3cfe1">
28+
<link rel="stylesheet" href="/assets/css/style.css?v=d5f139eb8f176587f80617439be596797a33067f">
2929
<!-- Custom stylesheet link (make sure it's compiled from assets/css/style.scss) -->
30-
<link rel="stylesheet" href="/assets/css/style.css?v=02f67b8d60b771c625d1b67fd8130dff34e3cfe1">
30+
<link rel="stylesheet" href="/assets/css/style.css?v=d5f139eb8f176587f80617439be596797a33067f">
3131
</head>
3232
<body>
3333
<a id="skip-to-content" href="#content">Skip to the content.</a>
@@ -135,6 +135,100 @@ <h2 id="-contributing">🤝 Contributing</h2>
135135
<li>Friendly contributions are always welcome — even typo fixes</li>
136136
</ul>
137137

138+
<hr />
139+
<p><a id="run-this-site-locally"></a></p>
140+
141+
<h2 id="-run-this-site-locally-preview-before-pushing">🧩 Run this site locally (preview before pushing)</h2>
142+
143+
<blockquote>
144+
<p>💡 <strong>Note:</strong> Run all commands from your local terminal (VS Code → View → Terminal).</p>
145+
</blockquote>
146+
147+
<p>You can preview this GitHub Pages site locally using <strong>Jekyll</strong> — the same engine GitHub uses — so you don’t have to commit every tiny CSS tweak like I did. 🫠</p>
148+
149+
<h3 id="-option-a-ruby--bundler-recommended">🔧 Option A: Ruby + Bundler (recommended)</h3>
150+
151+
<ol>
152+
<li>
153+
<p><strong>Install Bundler</strong> (macOS/Linux):</p>
154+
155+
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code> gem <span class="nb">install </span>bundler
156+
</code></pre></div> </div>
157+
</li>
158+
<li>
159+
<p><strong>Add a Gemfile</strong> in the <code class="language-plaintext highlighter-rouge">docs/</code> folder:</p>
160+
161+
<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code> <span class="c1"># docs/Gemfile</span>
162+
<span class="n">source</span> <span class="s2">"https://rubygems.org"</span>
163+
164+
<span class="n">gem</span> <span class="s2">"github-pages"</span><span class="p">,</span> <span class="ss">group: :jekyll_plugins</span>
165+
<span class="n">gem</span> <span class="s2">"webrick"</span> <span class="c1"># required on Ruby 3+</span>
166+
</code></pre></div> </div>
167+
</li>
168+
<li>
169+
<p><strong>Install and serve</strong>:</p>
170+
171+
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code> <span class="nb">cd </span>docs
172+
bundle <span class="nb">install
173+
</span>bundle <span class="nb">exec </span>jekyll serve <span class="nt">--livereload</span>
174+
</code></pre></div> </div>
175+
</li>
176+
<li>
177+
<p><strong>Open the site</strong>:</p>
178+
179+
<ul>
180+
<li>http://127.0.0.1:4000</li>
181+
</ul>
182+
</li>
183+
</ol>
184+
185+
<blockquote>
186+
<p>Tip: leave the server running — edits to Markdown, CSS, and images will auto-reload.</p>
187+
</blockquote>
188+
189+
<hr />
190+
191+
<h3 id="-option-b-docker-no-local-ruby-needed">🐋 Option B: Docker (no local Ruby needed)</h3>
192+
193+
<ol>
194+
<li>
195+
<p>From the <strong>repo root</strong>, run:</p>
196+
197+
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>docker run <span class="nt">--rm</span> <span class="nt">-it</span> <span class="nt">-p</span> 4000:4000 <span class="nt">-v</span> <span class="s2">"</span><span class="nv">$PWD</span><span class="s2">"</span>:/srv/jekyll jekyll/jekyll <span class="se">\</span>
198+
jekyll serve <span class="nt">--source</span> docs <span class="nt">--livereload</span>
199+
</code></pre></div> </div>
200+
</li>
201+
<li>
202+
<p><strong>Open the site</strong>:</p>
203+
204+
<ul>
205+
<li>http://127.0.0.1:4000</li>
206+
</ul>
207+
</li>
208+
</ol>
209+
210+
<hr />
211+
212+
<h3 id="-troubleshooting-running-the-site-locally">🧹 Troubleshooting running the site locally</h3>
213+
214+
<ul>
215+
<li>
216+
<p><strong>Could not locate Gemfile</strong><br />
217+
Make sure the file exists at <code class="language-plaintext highlighter-rouge">docs/Gemfile</code> and you ran commands from <code class="language-plaintext highlighter-rouge">docs/</code>.</p>
218+
</li>
219+
<li>
220+
<p><strong>CSS not updating</strong><br />
221+
If the browser is caching, hard-reload or open a private window.<br />
222+
If needed, stop and restart the Jekyll server.</p>
223+
</li>
224+
<li>
225+
<p><strong>Port already in use</strong><br />
226+
Try a different port:</p>
227+
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>bundle <span class="nb">exec </span>jekyll serve <span class="nt">--livereload</span> <span class="nt">--port</span> 4001
228+
</code></pre></div> </div>
229+
</li>
230+
</ul>
231+
138232
<hr />
139233

140234
<h2 id="-license">📄 License</h2>
@@ -179,6 +273,7 @@ <h3 id="table-of-contents">Table of Contents</h3>
179273
<li><a href="#troubleshooting">Troubleshooting</a></li>
180274
<li><a href="#additional-notes">Additional Notes</a></li>
181275
<li><a href="#conclusion">Conclusion</a></li>
276+
<li><a href="#support-this-project">Support this project</a></li>
182277
<li><a href="#license">License</a></li>
183278
</ul>
184279

@@ -676,7 +771,7 @@ <h3 id="️-optional-improve-udp-forwarding-performance">⚙️ Optional: Improv
676771
</li>
677772
</ol>
678773

679-
<p>Credit to <a href="https://gitlab.com/brkdncr">@brkdncr</a> for surfacing this tip and sharing a reproducible service example (<a href="https://github.com/johnnyfivepi/tailscale-on-raspberry-pi/issues/1">Issue #1</a>).</p>
774+
<p>Credit to <a href="https://github.com/brkdncr">@brkdncr</a> for surfacing this tip and sharing a reproducible service example (<a href="https://github.com/johnnyfivepi/tailscale-on-raspberry-pi/issues/1">Issue #1</a>).</p>
680775

681776
<hr />
682777

@@ -694,6 +789,13 @@ <h3 id="conclusion">Conclusion</h3>
694789

695790
<p>Self-hosting a VPN (and setting up an exit node) with Tailscale on a Raspberry Pi is not only fun but also a great way to improve your privacy and security while browsing the internet. If you’re interested in building a similar setup or want to ask questions about the process as I experienced it, feel free to leave a comment or reach out.</p>
696791

792+
<hr />
793+
794+
<p><strong>Maintainer note:</strong> Want to edit or contribute to this guide?<br />
795+
See <a href="#run-this-site-locally">🧩 Run this site locally</a> for setup instructions.</p>
796+
797+
<hr />
798+
697799
<h3 id="support-this-project">Support this project</h3>
698800

699801
<p>Thank you, reader, for following along with me!</p>

‎docs/_site/index.md‎

Lines changed: 82 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,79 @@ Suggestions, improvements, or ideas? I'd love your input!
8181
- Found a better workaround for DNS or routing? Share it!
8282
- Friendly contributions are always welcome — even typo fixes
8383

84+
---
85+
<a id="run-this-site-locally"></a>
86+
87+
## 🧩 Run this site locally (preview before pushing)
88+
89+
> 💡 **Note:** Run all commands from your local terminal (VS Code → View → Terminal).
90+
91+
You can preview this GitHub Pages site locally using **Jekyll** — the same engine GitHub uses — so you don’t have to commit every tiny CSS tweak like I did. 🫠
92+
93+
### 🔧 Option A: Ruby + Bundler (recommended)
94+
95+
1. **Install Bundler** (macOS/Linux):
96+
97+
```bash
98+
gem install bundler
99+
```
100+
101+
2. **Add a Gemfile** in the `docs/` folder:
102+
103+
```ruby
104+
# docs/Gemfile
105+
source "https://rubygems.org"
106+
107+
gem "github-pages", group: :jekyll_plugins
108+
gem "webrick" # required on Ruby 3+
109+
```
110+
111+
3. **Install and serve**:
112+
113+
```bash
114+
cd docs
115+
bundle install
116+
bundle exec jekyll serve --livereload
117+
```
118+
119+
4. **Open the site**:
120+
121+
- http://127.0.0.1:4000
122+
123+
> Tip: leave the server running — edits to Markdown, CSS, and images will auto-reload.
124+
125+
---
126+
127+
### 🐋 Option B: Docker (no local Ruby needed)
128+
129+
1. From the **repo root**, run:
130+
131+
```bash
132+
docker run --rm -it -p 4000:4000 -v "$PWD":/srv/jekyll jekyll/jekyll \
133+
jekyll serve --source docs --livereload
134+
```
135+
136+
2. **Open the site**:
137+
138+
- http://127.0.0.1:4000
139+
140+
---
141+
142+
### 🧹 Troubleshooting running the site locally
143+
144+
- **Could not locate Gemfile**
145+
Make sure the file exists at `docs/Gemfile` and you ran commands from `docs/`.
146+
147+
- **CSS not updating**
148+
If the browser is caching, hard-reload or open a private window.
149+
If needed, stop and restart the Jekyll server.
150+
151+
- **Port already in use**
152+
Try a different port:
153+
```bash
154+
bundle exec jekyll serve --livereload --port 4001
155+
```
156+
84157
---
85158

86159
## 📄 License
@@ -121,6 +194,7 @@ Do you have a spare Raspberry Pi lying around just waiting for a fun project? If
121194
- [Troubleshooting](#troubleshooting)
122195
- [Additional Notes](#additional-notes)
123196
- [Conclusion](#conclusion)
197+
- [Support this project](#support-this-project)
124198
- [License](#license)
125199
126200
---
@@ -488,7 +562,7 @@ To enable **UDP GRO forwarding** permanently:
488562
rx-udp-gro-forwarding: on
489563
```
490564
491-
Credit to [@brkdncr](https://gitlab.com/brkdncr) for surfacing this tip and sharing a reproducible service example ([Issue #1](https://github.com/johnnyfivepi/tailscale-on-raspberry-pi/issues/1)).
565+
Credit to [@brkdncr](https://github.com/brkdncr) for surfacing this tip and sharing a reproducible service example ([Issue #1](https://github.com/johnnyfivepi/tailscale-on-raspberry-pi/issues/1)).
492566
493567
---
494568
@@ -504,6 +578,13 @@ Credit to [@brkdncr](https://gitlab.com/brkdncr) for surfacing this tip and shar
504578
505579
Self-hosting a VPN (and setting up an exit node) with Tailscale on a Raspberry Pi is not only fun but also a great way to improve your privacy and security while browsing the internet. If you're interested in building a similar setup or want to ask questions about the process as I experienced it, feel free to leave a comment or reach out.
506580

581+
---
582+
583+
**Maintainer note:** Want to edit or contribute to this guide?
584+
See [🧩 Run this site locally](#run-this-site-locally) for setup instructions.
585+
586+
---
587+
507588
### Support this project
508589

509590
Thank you, reader, for following along with me!

0 commit comments

Comments
 (0)