Skip to content

Commit 0cb5d08

Browse files
rideamrideam
committed
text updates
1 parent 930afb3 commit 0cb5d08

File tree

2 files changed

+305
-0
lines changed

2 files changed

+305
-0
lines changed

‎sidebar.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -477,6 +477,10 @@
477477
"name": "3D Rendering with Three.js",
478478
"slug": "38-3D-rendering-with-threejs"
479479
},
480+
{
481+
"name": "Multi-user static blog with Nix",
482+
"slug": "40-multiuser-static-blog-with-nix"
483+
},
480484
{
481485
"name": "Pinboard project part 1: HTML & CSS",
482486
"slug": "pinboard-project-part-1"

‎tutorials/40-multiuser-static-blog-with-nix.md‎

Lines changed: 301 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,301 @@
1+
# Run a multi-user static blog on Replit with Nix and Hugo
2+
3+
In this tutorial, we will detail how you can use Replit to write and publish a blog or website. This can be a solo endeavour or a group or company blog. We'll build on the versatile Nix repl, using a static site generator called [Hugo](https://gohugo.io/) to ensure our site is fast, secure and flexible. We'll also use some repl tricks which will allow us to develop and host our blog without ever leaving Replit.
4+
5+
<video width="800" autoplay loop>
6+
<source src="/images/tutorials/40-multiuser-blog-nix/blogdemo.mp4" type="video/mp4">
7+
</video>
8+
9+
10+
After this tutorial, you will:
11+
12+
* Be familiar with setting up a static website using Hugo.
13+
* Understand how to connect multiple repls through GitHub.
14+
* Find new uses for Replit's collaborative features.
15+
16+
## Repl architecture
17+
18+
This project will make use of two repls:
19+
20+
* A **development repl**, which will be used to write and preview draft posts and make site changes. This repl will be where all development happens.
21+
* A **production repl**, which will be used to host a public version of the site. This repl will be updated from GitHub when new posts are made public.
22+
23+
If you have a premium Replit plan, you might want to make these repls private, to prevent people from finding your unfinished posts.
24+
25+
## Creating the working repl
26+
27+
Log into your [Replit account](https://replit.com/login) and create a new repl. Choose Nix as your project type. Give this repl a name, like "blog-dev".
28+
29+
![Creating the development repl](/images/tutorials/40-multiuser-blog-nix/dev-repl.png)
30+
31+
Most kinds of repls are intended for working in a specific programming language or framework, such as Python or Kaboom.js. Nix repls are different: you can think of them as a blank slate for running anything you want. So the first thing we need to do in our repl is define what we're going to run – in this case it will be Hugo. Open `replit.nix` and append `pkgs.hugo` to the `deps` list. Your file should look like this:
32+
33+
```nix
34+
{ pkgs }: {
35+
deps = [
36+
pkgs.cowsay
37+
pkgs.hugo
38+
];
39+
}
40+
```
41+
42+
This will install Hugo the next time we run our repl. If you'd like to understand more about what this code is actually doing, check out the tutorial on [building with Nix on Replit](https://docs.replit.com/tutorials/30-build-with-nix).
43+
44+
Run your repl now. Once you see the ASCII cow in the repl console, type the following command:
45+
46+
```sh
47+
hugo new site --force .
48+
```
49+
50+
This will create a new Hugo site in our repl. The `--force` flag is necessary because Hugo usually doesn't like creating new sites in directories that already contain files.
51+
52+
You should now see a number of new directories and files in your repl's filepane. This is the skeleton of your Hugo site. Don't worry about what each of these files and directories are for – you only need to know about a few of them to start blogging, and we'll explain them as we go.
53+
54+
<img src="/images/tutorials/40-multiuser-blog-nix/hugo-files.png"
55+
alt="hugo files"
56+
style="width: 40% !important;"/>
57+
58+
59+
Because Hugo is highly flexible and unopinionated, it doesn't even come with a default theme, so we won't be able to see our site in action until we choose one. There are a large number of choices on [Hugo's official themes website](https://themes.gohugo.io/). For this tutorial, we'll be using [Radek Kozieł](https://radoslawkoziel.pl/)'s [Terminal](https://themes.gohugo.io/themes/hugo-theme-terminal/) theme, but feel free to pick a different one later.
60+
61+
To install the theme, run the following command in your repl's console:
62+
63+
```sh
64+
cd themes && git clone https://github.com/panr/hugo-theme-terminal && cd ..
65+
```
66+
67+
This will use Git to download the theme into our site's `themes` directory. To instruct our site to use this theme, add the following line to the bottom of `config.toml`:
68+
69+
```toml
70+
theme = 'hugo-theme-terminal'
71+
```
72+
73+
We must now configure our repl to host our static site so that we can see the results of our work. If you're familiar with static site generators (perhaps from a [previous tutorial](https://docs.replit.com/tutorials/16-static-site-generator)), you'll know that this is a two-step process:
74+
75+
1. Render content in markdown and insert it into theme templates to create HTML pages.
76+
2. Host those HTML pages on a webserver.
77+
78+
Hugo includes a built-in command that does both, [`hugo server`](https://gohugo.io/commands/hugo_server/). We can make this the command that executes when we click our repl's run button by editing the `run` directive in the `.replit` file as below:
79+
80+
```sh
81+
run = "hugo server --buildDrafts --buildFuture --bind 0.0.0.0 --port 443 --baseURL https://YOUR-REPL-NAME-HERE.YOUR-USERNAME-HERE.repl.co"
82+
```
83+
84+
In this command:
85+
86+
* `--buildDrafts` and `--buildFuture` will ensure that all site content is rendered, even if it's marked as a draft or scheduled for publishing in the future.
87+
* `--bind` `--port` and `--baseURL` are all used to [ensure that our repl will host our site correctly](https://docs.replit.com/hosting/deploying-http-servers). Make sure to modify the argument for `--baseURL` as indicated i.e. replacing the placeholders `YOUR-REPL-NAME-HERE` and `YOUR-USERNAME-HERE` with your own values.
88+
89+
Run your repl. You should see an empty site homepage.
90+
91+
![Empty home page](/images/tutorials/40-multiuser-blog-nix/empty-site.png)
92+
93+
To create your first post, run the command below in the repl shell. Press Y when prompted to run Hugo from Nix:
94+
95+
```sh
96+
hugo new posts/first-post.md
97+
```
98+
99+
Your site will automatically reload and should now look like this:
100+
101+
![First post](/images/tutorials/40-multiuser-blog-nix/first-post.png)
102+
103+
You should see a file named `first-post.md` in the `content/posts` directory with contents resembling the following:
104+
105+
```markdown
106+
+++
107+
title = "First Post"
108+
date = "2022-01-30T11:21:41Z"
109+
author = "Your name"
110+
authorTwitter = "Your Twitter"
111+
cover = ""
112+
tags = ["", ""]
113+
keywords = ["", ""]
114+
description = ""
115+
showFullContent = false
116+
readingTime = false
117+
+++
118+
119+
```
120+
121+
The text between the `+++` lines is called [front matter](https://gohugo.io/content-management/front-matter/) and defines metadata for your post, such as its title, author and time posted. Post content can be added as markdown-formatted text below the final `+++`. Add some now.
122+
123+
```markdown
124+
+++
125+
title = "First Post"
126+
date = "2022-01-30T11:21:41Z"
127+
author = "Your name"
128+
authorTwitter = "Your Twitter"
129+
cover = ""
130+
tags = ["", ""]
131+
keywords = ["", ""]
132+
description = ""
133+
showFullContent = false
134+
readingTime = false
135+
+++
136+
137+
## Hello world!
138+
139+
This *is* **my** `first` post!
140+
141+
```
142+
143+
![Post Content](/images/tutorials/40-multiuser-blog-nix/post-content.png)
144+
145+
## Preparing for production
146+
147+
We now have a functional workspace in which to develop our site, but we need to make a few alterations before it's ready for public consumption. First, let's make it easier to keep unfinished posts as drafts. By default, posts created using the Terminal theme will appear as published as soon as they're created – this is probably not what we want. Luckily, it's an easy fix.
148+
149+
Hugo stores content templates in a directory called [archetypes](https://gohugo.io/content-management/archetypes/). You should see an empty directory with this name in your repl's file pane. Archetype files are named after the content type (e.g. post or page) they're used for – currently, our `archetypes` directory only has a single file, named `default.md`, which will be used for content types without custom archetypes. However, if you look at the contents of `default.md`, you'll notice that it looks nothing like the post we created above. This is because Hugo doesn't just look for archetypes in our site skeleton, but also in our chosen theme.
150+
151+
You should find a file named `posts.md` in `themes/hugo-terminal-theme/archetypes/posts.md`. The contents of this file will resemble the new post you made in the last section. Duplicate this file, move it into your top-level `archetypes` directory, and rename it to `posts.md`. Then, in the new file, add the line `draft = true` just above the final `+++`. Your `archetypes/posts.md` file should look like this:
152+
153+
```md
154+
+++
155+
title = "{{ replace .TranslationBaseName "-" " " | title }}"
156+
date = "{{ .Date }}"
157+
author = ""
158+
authorTwitter = "" #do not include @
159+
cover = ""
160+
tags = ["", ""]
161+
keywords = ["", ""]
162+
description = ""
163+
showFullContent = false
164+
readingTime = false
165+
draft = true
166+
+++
167+
168+
```
169+
170+
If a file in a top-level directory has the same name as a file in the equivalent theme directory, the former will override the latter. This allows us to make site-specific tweaks without changing our theme. Create a new post by entering the following command into your repl's shell:
171+
172+
```sh
173+
hugo new posts/second-post.md
174+
```
175+
176+
This post and all subsequent new posts will be marked as drafts, and will thus only be included in our website if we run Hugo with the `--buildDrafts` flag. This will be useful for when we create our production repl. But before we can do that, we need to prepare this development repl to connect to it by creating a GitHub repository.
177+
178+
Select the version control tab in your repl's side-pane and click on **Create a Git Repo**. This will create a local repository to track your code changes. From here, you can create snapshots of your code (called commits), which can you can revert to if needed.
179+
180+
<img src="/images/tutorials/40-multiuser-blog-nix/create-repo.png"
181+
alt="Creating a GitHub repo"
182+
style="width: 40% !important;"/>
183+
184+
185+
To push our repl to a repository on GitHub, we'll need a GitHub account. [Create one](https://github.com/signup) if you haven't before. Once you've created an account or logged into your existing one, return to your repl and click on **Connect to GitHub**. Accept the Oauth confirmation message that appears.
186+
187+
<img src="/images/tutorials/40-multiuser-blog-nix/connect-github.png"
188+
alt="Connect to GitHub"
189+
style="width: 40% !important;"/>
190+
191+
Replit will then prompt you to specify a repository name, optional description and privacy setting. You can call your repository "blog". If you have a paid Replit plan, you can make it private, otherwise it will have to be public. Once you've created the GitHub repository, you'll be able to view it on your GitHub account.
192+
193+
![GitHub repo](/images/tutorials/40-multiuser-blog-nix/github-repo.png)
194+
195+
Now that your repl is connected to a GitHub repository, any time you make changes, those will be reflected in the version control tab. To commit those changes and push them to your GitHub repository, you can click on **Commit and push** in your repl's version control tab. You will be required to specify a commit message describing the changes you've made.
196+
197+
If our production repl will be sharing a code repository with our development repl, how will we ensure that drafts and future content aren't shown in production? One solution might be to use different branches, but that would require constant merging. All that really needs to change between development and production is the command that gets executed when we click the Run button. We'll use a bit of repl magic to make this work.
198+
199+
First, replace the `run` directive in the `.replit` config file with the following:
200+
201+
```sh
202+
run = "sh run.sh"
203+
```
204+
205+
Then create a file named `run.sh` and add the following code to it:
206+
207+
```sh
208+
#!/bin/bash
209+
210+
if [ "$REPL_SLUG" == 'blog-dev' ] # draft space
211+
then
212+
hugo serve --buildDrafts --buildFuture --bind 0.0.0.0 --port 443 --baseURL https://$REPL_SLUG.$REPL_OWNER.repl.co
213+
else # production
214+
hugo serve --bind 0.0.0.0 --port 443 --baseURL https://$REPL_SLUG.$REPL_OWNER.repl.co
215+
fi
216+
```
217+
218+
Here we've used a couple of [repl metadata environment variables](https://docs.replit.com/programming-ide/getting-repl-metadata) to trigger different behavior when our code is run in different repls.
219+
220+
Return to your repl's version control tab and commit and push your changes. We are now ready to create the production repl.
221+
222+
<img src="/images/tutorials/40-multiuser-blog-nix/commitpush.png"
223+
alt="Commit and push to GitHub"
224+
style="width: 40% !important;"/>
225+
226+
## Creating the production repl
227+
228+
Fork your development repl. Give the new repl a different name, such as "blog".
229+
230+
<img src="/images/tutorials/40-multiuser-blog-nix/fork-repl.png"
231+
alt="Fork repl"
232+
style="width: 60% !important;"/>
233+
234+
Since we've forked our development repl, both repls will be backed by the same repository on GitHub. This means we can commit and push changes from one repl (development) and pull those changes into the other repl (production). We could also achieve this by creating a new repl from our GitHub repository, but forking is quicker.
235+
236+
When your production repl is run, you should see an almost identical website to the one in your development repl. The only difference should be that the second post won't appear in the production repl, as it is a draft.
237+
238+
Let's test out our publishing flow.
239+
240+
1. In your **development** repl, add some text to `content/posts/second-post.md`. Specify some or all of the front matter, such as your author name and Twitter account.
241+
2. Set `draft = false` in the post's front matter.
242+
3. From the **development** repl's version control tab, commit and push your changes.
243+
4. In your **production** repl, navigate to the version control tab and click on the "← Pull" link. This will pull the changes we just pushed from development.
244+
245+
<img src="/images/tutorials/40-multiuser-blog-nix/pull.png" alt="Pull from GitHub" style="width: 40% !important;"/>
246+
247+
6. Rerun your **production** repl. You should now see the contents of the second blog post live on the website.
248+
249+
This will be your workflow for publishing posts. Undraft, commit and push on development, then pull and rerun on production.
250+
251+
If you have a paid Replit plan, you should set your production repl as [Always-on](https://docs.replit.com/hosting/enabling-always-on), so that people will always be able to reach your website.
252+
253+
You will probably also want to use a custom domain name, instead of `blog.your-name.repl.co`. Instructions for [setting this up are provided here](https://docs.replit.com/hosting/hosting-web-pages#custom-domains). As a bonus, following this process will also put your site behind [Cloudflare](https://www.cloudflare.com/)'s content delivery network (CDN), improving its performance and reachability across the global internet. Cloudflare is [free for personal and hobby projects](https://www.cloudflare.com/plans/#overview).
254+
255+
## Writing posts
256+
257+
Now that we have a publishing platform in place, let's take a more detailed look at how to create content in Hugo.
258+
259+
The basis of all Hugo blogs is Markdown, a simple mark-up language for the web, [originally created in 2004 by John Gruber](https://daringfireball.net/projects/markdown/). Markdown provides a simple, limited syntax, focused on the common needs of bloggers and other web-based writers. Basic Markdown elements are limited to headings, **bold**, `italic` and `code-style` text, blockquotes, lists, code blocks, horizontal rules, links and images. Markdown has been extended over the years to provide more advanced formatting, such as tables and footnotes. A cheat sheet covering both basic and extended [syntax can be found here](https://www.markdownguide.org/cheat-sheet/) (Hugo supports both basic and extended Markdown).
260+
261+
To include images in your posts, upload them to the `static` directory. All files and subdirectories in `static` will be rendered as-is from our website's root URL. For example, if you create a file named `static/images/pic.png`, you will be able to include it in your posts by writing `![](/images/pic.png)`. You can put anything you want in `static`, including documents, audio files, or even videos.
262+
263+
If you want formatting that isn't included in Markdown, such as colored text, you can add HTML and CSS to your posts directly, but first you must configure Hugo's Markdown parser (Goldmark) to accept unsafe input. Add the following lines to `config.toml`:
264+
265+
```toml
266+
[markup.goldmark.renderer]
267+
unsafe = true
268+
```
269+
270+
Stop and start your repl for the config change to take effect.
271+
272+
Hugo also provides functionality called [shortcodes](https://gohugo.io/content-management/shortcodes/), which you can think of as HTML [macros](https://en.wikipedia.org/wiki/Macro_(computer_science)). Hugo provides built-in shortcodes for common tasks such as embedding [tweets](https://gohugo.io/content-management/shortcodes/#tweet) and [YouTube videos](https://gohugo.io/content-management/shortcodes/#youtube). You can also [create your own custom shortcodes](https://gohugo.io/templates/shortcode-templates/).
273+
274+
Replit's multiplayer editing features aren't only good for collaborative programming, but can also be used for collaborative blogging. Multiple users can work in the same file in real-time, and you can use [inline code threads](https://blog.replit.com/threads) to leave each other feedback and discuss individual words and sentences.
275+
276+
![Collaboration chat](/images/tutorials/40-multiuser-blog-nix/thread.png)
277+
278+
If you need to include diagrams in your blog posts, you can draw them using [your repl's built-in Excalidraw](https://blog.replit.com/draw). Just create a new file with a `.draw` extension and start diagramming. When you're done, select your diagram, right-click and chose "Copy to clipboard as SVG". Then paste into the post you want to include the diagram in. Note that the Goldmark must be configured in the manner shown above for this to work, as SVG images are part of HTML.
279+
280+
<img src="/images/tutorials/40-multiuser-blog-nix/diagram.png"
281+
alt="Drawing on Replit"
282+
style="width: 60% !important;"/>
283+
284+
## Where next?
285+
286+
You've now got a fully functional static blog hosted on Replit. Some things you might want to do with it:
287+
288+
* Learn more about Hugo from [the official documentation](https://gohugo.io/documentation/).
289+
* Choose a different theme from the [Hugo themes showcase](https://themes.gohugo.io/) or [create your own](https://gohugo.io/commands/hugo_new_theme/).
290+
* Get a few collaborators and write some more blog posts.
291+
292+
You can find our development and production repls below:
293+
294+
**Development**
295+
296+
<iframe height="400px" width="100%" src="https://replit.com/@ritza/blog-dev?embed=true" scrolling="no" frameborder="no" allowtransparency="true" allowfullscreen="true" sandbox="allow-forms allow-pointer-lock allow-popups allow-same-origin allow-scripts allow-modals"></iframe>
297+
298+
**Production**
299+
300+
<iframe height="400px" width="100%" src="https://replit.com/@ritza/blog-prod?embed=true" scrolling="no" frameborder="no" allowtransparency="true" allowfullscreen="true" sandbox="allow-forms allow-pointer-lock allow-popups allow-same-origin allow-scripts allow-modals"></iframe>
301+

0 commit comments

Comments
 (0)