feat(blog): 使用 Xray、acme.sh、Docker Compose 搭建内网穿透服务。
All checks were successful
continuous-integration/drone/push Build is passing
All checks were successful
continuous-integration/drone/push Build is passing
This commit is contained in:
parent
0c74f2f7a6
commit
97c637f050
3
.vscode/settings.json
vendored
Normal file
3
.vscode/settings.json
vendored
Normal file
@ -0,0 +1,3 @@
|
||||
{
|
||||
"cSpell.words": ["alpn", "blackhole", "dokodemo", "fullchain", "outbounds", "rprx", "xtls"]
|
||||
}
|
||||
271
data/blog/build-an-frp-using-xray-acme.sh-docker-compose.md
Normal file
271
data/blog/build-an-frp-using-xray-acme.sh-docker-compose.md
Normal file
@ -0,0 +1,271 @@
|
||||
---
|
||||
title: 使用 Xray、acme.sh、Docker Compose 搭建内网穿透服务
|
||||
date: '2022-06-11'
|
||||
tags: ['xray', 'acme', 'acme.sh', 'docker', 'docker compose', '内网穿透']
|
||||
draft: false
|
||||
summary: 为了能在外直接访问家中网络，我组建了三套方案，一是 [[Xray]]，二是 [[ZeroTier]]，三是 [[NPS]]。今天，我准备在我上个月购入的服务器上再部署一套 Xray 服务，提高可用性。本次准备完全仰仗 Docker 容器，让我未来迁移服务更加省事。
|
||||
---
|
||||
|
||||
## 简介
|
||||
|
||||
为了能在外直接访问家中网络，我组建了三套方案，一是 [Xray](/tags/xray)，二是 [ZeroTier](/tags/zerotier)，三是 [NPS](/tags/nps)。今天，我准备在我上个月购入的服务器上再部署一套 Xray 服务，提高可用性。本次准备完全仰仗 Docker 容器，让我未来迁移服务更加省事。
|
||||
|
||||
## 目标与方案
|
||||
|
||||
个人自用，成本得控制到零(bushi)，安全性还是得做得好些，所以选用 Xray 来承载功能，使用免费的 TLS CA 来签发证书。由于免费的证书一般有效期比较短 (常见的是 90 天)，所以还需要实现自动续签。
|
||||
Let's Encrypt 和 acme.sh 是不错的组合。不过听说 Let's Encrypt 被收购了，不知道是否有安全风险，未来需要再确认下。由于财力并不雄厚，考虑到未来可能服务会”流离失所“，用容器方案比较好迁移。
|
||||
|
||||
## 技术栈
|
||||
|
||||
- Xray
|
||||
一款支持加密传输、内网穿透的网络工具。由 GoLang 编写，支持很多平台。
|
||||
_官方站点：[Project X](https://xtls.github.io/)_
|
||||
- acme.sh
|
||||
用于签发 TLS 证书。顾名思义，支持 ACME 协议签发、自动续签证书的脚本。
|
||||
_官方站点：[acmesh-official/acme.sh](https://github.com/acmesh-official/acme.sh)_
|
||||
- Caddy
|
||||
用于反向代理部署在家里的 Web 服务。它是现代的反向代理服务。
|
||||
_官方站点：[Caddy 2](https://caddyserver.com/v2)_
|
||||
- Docker Compose
|
||||
众所周知？
|
||||
|
||||
## 搭建步骤
|
||||
|
||||
### Docker Compose
|
||||
|
||||
首先需要拥有并运行 Docker 和 Docker Compose。
|
||||
创建一个用于存放配置文件目录，并进入该目录。
|
||||
创建 Compose 配置文件：
|
||||
|
||||
```bash
|
||||
touch docker-compose.yml
|
||||
vim docker-compose.yml
|
||||
```
|
||||
|
||||
文件内容：
|
||||
|
||||
```yaml
|
||||
version: '3.9'
|
||||
|
||||
networks:
|
||||
caddy:
|
||||
name: caddy
|
||||
xray:
|
||||
name: xray
|
||||
|
||||
volumes:
|
||||
caddy-data:
|
||||
name: caddy-data
|
||||
caddy-config:
|
||||
name: caddy-config
|
||||
acme-sh-data:
|
||||
name: acme-sh-data
|
||||
|
||||
services:
|
||||
caddy:
|
||||
image: caddy:2
|
||||
container_name: caddy
|
||||
restart: always
|
||||
ports:
|
||||
- 80:80
|
||||
- 443:443
|
||||
networks:
|
||||
- caddy
|
||||
volumes:
|
||||
- $PWD/caddy/Caddyfile:/etc/caddy/Caddyfile
|
||||
- $PWD/site:/srv
|
||||
- caddy-data:/data
|
||||
- caddy-config:/config
|
||||
|
||||
xray:
|
||||
image: teddysun/xray
|
||||
container_name: xray
|
||||
restart: always
|
||||
networks:
|
||||
- xray
|
||||
- caddy
|
||||
ports:
|
||||
- 3332-3334:3332-3334
|
||||
volumes:
|
||||
- ./xray:/etc/xray
|
||||
- acme-sh-data:/certs
|
||||
command: "xray -c=/etc/xray/config.yml"
|
||||
|
||||
acme.sh:
|
||||
image: neilpang/acme.sh
|
||||
container_name: acme.sh
|
||||
# restart: always
|
||||
volumes:
|
||||
- acme-sh-data:/acme.sh
|
||||
env_file: acme.env
|
||||
command: "daemon"
|
||||
|
||||
```
|
||||
|
||||
### 签发证书
|
||||
|
||||
使用 DNS Challenge 来签发证书，所以需要 DNS 服务商的 API 来实现自动化签发流程。
|
||||
|
||||
以阿里云举例：
|
||||
|
||||
1. 创建 RAM 子账户，并只允许访问 API；
|
||||
2. 复制 key 和 secret；
|
||||
3. 为 RAM 子账户授权 DNS 解析的管理权限。
|
||||
|
||||
在当前目录创建 `acme.env` 文件：
|
||||
|
||||
```zsh
|
||||
touch acme.env
|
||||
vim acme.env
|
||||
```
|
||||
|
||||
文件内容：
|
||||
|
||||
```zsh
|
||||
Ali_Key="sdfsdfsdfljlbjkljlkjsdfoiwje"
|
||||
Ali_Secret="jlsdflanljkljlfdsaklkjflsa"
|
||||
```
|
||||
|
||||
启动 compose 服务：
|
||||
|
||||
```zsh
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
前面我们启动了刚刚创建的 compose 服务，现在，我们使用 `acme.sh` 容器运行以下命令签发证书：
|
||||
|
||||
```zsh
|
||||
docker exec acme.sh acme.sh --log --issue --dns dns_ali --server letsencrypt -d ivanli.cc -d "*.ivanli.cc"
|
||||
```
|
||||
|
||||
签发成功后你将会在输出末尾看到如下内容：
|
||||
|
||||
|
||||
注意，签发通配符证书时，需要一次性将所有通配的子域都写在同一条命令上，使用 `-d` 参数追加。
|
||||
|
||||
### 配置 Xray
|
||||
|
||||
因为前面挂载了 `acme.sh` 的数据卷，所以默认的证书位于 `/certs/ivanli.cc/` 目录下。证书要使用 `fullchain` 的，避免证书链不完整，导致客户端连接验证失败。
|
||||
|
||||
创建 Xray 配置文件：
|
||||
|
||||
```zsh
|
||||
mkdir ./xray
|
||||
vim ./xray/config.yml
|
||||
```
|
||||
|
||||
内容如下：
|
||||
|
||||
```yml
|
||||
inbounds:
|
||||
# listening for host-name.home
|
||||
- tag: host-name.home.in
|
||||
listen: 0.0.0.0
|
||||
port: 3332
|
||||
protocol: vless
|
||||
settings:
|
||||
clients:
|
||||
- id: <uuid> # 你的 UUID
|
||||
flow: xtls-rprx-direct
|
||||
decryption: none
|
||||
streamSettings:
|
||||
network: tcp
|
||||
security: xtls
|
||||
xtlsSettings:
|
||||
serverName: ivanli.cc
|
||||
alpn:
|
||||
- http/1.1
|
||||
certificates:
|
||||
- certificateFile: /certs/ivanli.cc/fullchain.cer
|
||||
keyFile: /certs/ivanli.cc/ivanli.cc.key
|
||||
|
||||
# reverse ssh to host-name.home
|
||||
- tag: ssh.host-name.home.in
|
||||
listen: 0.0.0.0
|
||||
port: 3334
|
||||
protocol: dokodemo-door
|
||||
settings:
|
||||
network: tcp
|
||||
address: 127.0.0.1
|
||||
port: 22
|
||||
# reverse http to 101.home
|
||||
- tag: http.host-name.home.in
|
||||
listen: 0.0.0.0
|
||||
port: 3333
|
||||
protocol: dokodemo-door
|
||||
settings:
|
||||
network: tcp
|
||||
address: 127.0.0.1
|
||||
port: 80
|
||||
|
||||
outbounds:
|
||||
- protocol: freedom
|
||||
tag: direct
|
||||
- tag: blocked
|
||||
protocol: blackhole
|
||||
|
||||
reverse:
|
||||
portals:
|
||||
- tag: host-name.home.portal
|
||||
domain: host-name.home.reverse
|
||||
|
||||
routing:
|
||||
- type: field
|
||||
inboundTag:
|
||||
- ssh.host-name.home.in
|
||||
- http.host-name.home.in
|
||||
outboundTag: host-name.home.portal
|
||||
- type: field
|
||||
domain:
|
||||
- full:host-name.home.reverse
|
||||
outboundTag: host-name.home.portal
|
||||
```
|
||||
|
||||
配置说明
|
||||
|
||||
- `3332` 端口用于客户端连接服务端；
|
||||
- `3333` 端口用于 HTTP 穿透，映射了 `server:3333 <--> client:80` 端口；
|
||||
- `3334` 端口用于 SSH 穿透。
|
||||
- 如果需要连接更多的内网主机和端口，可以继续依葫芦画瓢地加。
|
||||
|
||||
### 配置 Caddy
|
||||
|
||||
为了让我们的 Web 站点能够公开到互联网，并且增强可控性，没有直接公开 Xray 的端口，而是使用 Caddy 反向代理 Xray 的穿透的本地端口。
|
||||
|
||||
创建 Caddy 配置文件：
|
||||
|
||||
```zsh
|
||||
mkdir ./caddy
|
||||
vim ./caddy/Caddyfile
|
||||
```
|
||||
|
||||
内容如下：
|
||||
|
||||
```caddyfile
|
||||
{
|
||||
servers {
|
||||
protocol {
|
||||
allow_h2c
|
||||
}
|
||||
}
|
||||
admin off
|
||||
}
|
||||
|
||||
any-service.ivanli.cc, another-service.ivanli.cc {
|
||||
reverse_proxy http://localhost:3333
|
||||
}
|
||||
```
|
||||
|
||||
端口 `3333` 是 Xray Server 映射家里 HTTP 服务的端口，所以我们这里反向代理服务器上的 3333 端口就好了。
|
||||
|
||||
因为 Caddy 会自动从 CA 签发证书，所以这里不需要我们手动配置证书。
|
||||
|
||||
配置完成后，重启服务就好
|
||||
|
||||
```zsh
|
||||
docker-compose restart
|
||||
```
|
||||
|
||||
现在，你拥有一个安全的内网穿透服务了~
|
||||
用户通过 HTTPS 协议访问服务器，服务器通过 TLS 加密连接与内网主机通讯。
|
||||
TODO 自动重启
|
||||
@ -1,141 +0,0 @@
|
||||
---
|
||||
title: Deriving the OLS Estimator
|
||||
date: '2020-12-21'
|
||||
tags: ['next js', 'math', 'ols']
|
||||
draft: false
|
||||
summary: 'How to derive the OLS Estimator with matrix notation and a tour of math typesetting using markdown with the help of KaTeX.'
|
||||
---
|
||||
|
||||
# Introduction
|
||||
|
||||
Parsing and display of math equations is included in this blog template. Parsing of math is enabled by `remark-math` and `rehype-katex`.
|
||||
KaTeX and its associated font is included in `_document.js` so feel free to use it on any page.
|
||||
^[For the full list of supported TeX functions, check out the [KaTeX documentation](https://katex.org/docs/supported.html)]
|
||||
|
||||
Inline math symbols can be included by enclosing the term between the `$` symbol.
|
||||
|
||||
Math code blocks are denoted by `$$`.
|
||||
|
||||
If you intend to use the `$` sign instead of math, you can escape it (`\$`), or specify the HTML entity (`$`) [^2]
|
||||
|
||||
Inline or manually enumerated footnotes are also supported. Click on the links above to see them in action.
|
||||
|
||||
[^2]: \$10 and $20.
|
||||
|
||||
# Deriving the OLS Estimator
|
||||
|
||||
Using matrix notation, let $n$ denote the number of observations and $k$ denote the number of regressors.
|
||||
|
||||
The vector of outcome variables $\mathbf{Y}$ is a $n \times 1$ matrix,
|
||||
|
||||
```tex
|
||||
\mathbf{Y} = \left[\begin{array}
|
||||
{c}
|
||||
y_1 \\
|
||||
. \\
|
||||
. \\
|
||||
. \\
|
||||
y_n
|
||||
\end{array}\right]
|
||||
```
|
||||
|
||||
$$
|
||||
\mathbf{Y} = \left[\begin{array}
|
||||
{c}
|
||||
y_1 \\
|
||||
. \\
|
||||
. \\
|
||||
. \\
|
||||
y_n
|
||||
\end{array}\right]
|
||||
$$
|
||||
|
||||
The matrix of regressors $\mathbf{X}$ is a $n \times k$ matrix (or each row is a $k \times 1$ vector),
|
||||
|
||||
```latex
|
||||
\mathbf{X} = \left[\begin{array}
|
||||
{ccccc}
|
||||
x_{11} & . & . & . & x_{1k} \\
|
||||
. & . & . & . & . \\
|
||||
. & . & . & . & . \\
|
||||
. & . & . & . & . \\
|
||||
x_{n1} & . & . & . & x_{nn}
|
||||
\end{array}\right] =
|
||||
\left[\begin{array}
|
||||
{c}
|
||||
\mathbf{x}'_1 \\
|
||||
. \\
|
||||
. \\
|
||||
. \\
|
||||
\mathbf{x}'_n
|
||||
\end{array}\right]
|
||||
```
|
||||
|
||||
$$
|
||||
\mathbf{X} = \left[\begin{array}
|
||||
{ccccc}
|
||||
x_{11} & . & . & . & x_{1k} \\
|
||||
. & . & . & . & . \\
|
||||
. & . & . & . & . \\
|
||||
. & . & . & . & . \\
|
||||
x_{n1} & . & . & . & x_{nn}
|
||||
\end{array}\right] =
|
||||
\left[\begin{array}
|
||||
{c}
|
||||
\mathbf{x}'_1 \\
|
||||
. \\
|
||||
. \\
|
||||
. \\
|
||||
\mathbf{x}'_n
|
||||
\end{array}\right]
|
||||
$$
|
||||
|
||||
The vector of error terms $\mathbf{U}$ is also a $n \times 1$ matrix.
|
||||
|
||||
At times it might be easier to use vector notation. For consistency, I will use the bold small x to denote a vector and capital letters to denote a matrix. Single observations are denoted by the subscript.
|
||||
|
||||
## Least Squares
|
||||
|
||||
**Start**:
|
||||
$$y_i = \mathbf{x}'_i \beta + u_i$$
|
||||
|
||||
**Assumptions**:
|
||||
|
||||
1. Linearity (given above)
|
||||
2. $E(\mathbf{U}|\mathbf{X}) = 0$ (conditional independence)
|
||||
3. rank($\mathbf{X}$) = $k$ (no multi-collinearity i.e. full rank)
|
||||
4. $Var(\mathbf{U}|\mathbf{X}) = \sigma^2 I_n$ (Homoskedascity)
|
||||
|
||||
**Aim**:
|
||||
Find $\beta$ that minimises the sum of squared errors:
|
||||
|
||||
$$
|
||||
Q = \sum_{i=1}^{n}{u_i^2} = \sum_{i=1}^{n}{(y_i - \mathbf{x}'_i\beta)^2} = (Y-X\beta)'(Y-X\beta)
|
||||
$$
|
||||
|
||||
**Solution**:
|
||||
Hints: $Q$ is a $1 \times 1$ scalar, by symmetry $\frac{\partial b'Ab}{\partial b} = 2Ab$.
|
||||
|
||||
Take matrix derivative w.r.t $\beta$:
|
||||
|
||||
```tex
|
||||
\begin{aligned}
|
||||
\min Q & = \min_{\beta} \mathbf{Y}'\mathbf{Y} - 2\beta'\mathbf{X}'\mathbf{Y} +
|
||||
\beta'\mathbf{X}'\mathbf{X}\beta \\
|
||||
& = \min_{\beta} - 2\beta'\mathbf{X}'\mathbf{Y} + \beta'\mathbf{X}'\mathbf{X}\beta \\
|
||||
\text{[FOC]}~~~0 & = - 2\mathbf{X}'\mathbf{Y} + 2\mathbf{X}'\mathbf{X}\hat{\beta} \\
|
||||
\hat{\beta} & = (\mathbf{X}'\mathbf{X})^{-1}\mathbf{X}'\mathbf{Y} \\
|
||||
& = (\sum^{n} \mathbf{x}_i \mathbf{x}'_i)^{-1} \sum^{n} \mathbf{x}_i y_i
|
||||
\end{aligned}
|
||||
```
|
||||
|
||||
$$
|
||||
\begin{aligned}
|
||||
\min Q & = \min_{\beta} \mathbf{Y}'\mathbf{Y} - 2\beta'\mathbf{X}'\mathbf{Y} +
|
||||
\beta'\mathbf{X}'\mathbf{X}\beta \\
|
||||
& = \min_{\beta} - 2\beta'\mathbf{X}'\mathbf{Y} + \beta'\mathbf{X}'\mathbf{X}\beta \\
|
||||
\text{[FOC]}~~~0 & = - 2\mathbf{X}'\mathbf{Y} + 2\mathbf{X}'\mathbf{X}\hat{\beta} \\
|
||||
\hat{\beta} & = (\mathbf{X}'\mathbf{X})^{-1}\mathbf{X}'\mathbf{Y} \\
|
||||
& = (\sum^{n} \mathbf{x}_i \mathbf{x}'_i)^{-1} \sum^{n} \mathbf{x}_i y_i
|
||||
\end{aligned}
|
||||
$$
|
||||
@ -1,198 +0,0 @@
|
||||
---
|
||||
title: 'Markdown Guide'
|
||||
date: '2019-10-11'
|
||||
tags: ['github', 'guide']
|
||||
draft: false
|
||||
summary: 'Markdown cheatsheet for all your blogging needs - headers, lists, images, tables and more! An illustrated guide based on GitHub Flavored Markdown.'
|
||||
---
|
||||
|
||||
# Introduction
|
||||
|
||||
Markdown and Mdx parsing is supported via `unified`, and other remark and rehype packages. `next-mdx-remote` allows us to parse `.mdx` and `.md` files in a more flexible manner without touching webpack.
|
||||
|
||||
GitHub flavored markdown is used. `mdx-prism` provides syntax highlighting capabilities for code blocks. Here's a demo of how everything looks.
|
||||
|
||||
The following markdown cheatsheet is adapted from: https://guides.github.com/features/mastering-markdown/
|
||||
|
||||
# What is Markdown?
|
||||
|
||||
Markdown is a way to style text on the web. You control the display of the document; formatting words as bold or italic, adding images, and creating lists are just a few of the things we can do with Markdown. Mostly, Markdown is just regular text with a few non-alphabetic characters thrown in, like `#` or `*`.
|
||||
|
||||
# Syntax guide
|
||||
|
||||
Here’s an overview of Markdown syntax that you can use anywhere on GitHub.com or in your own text files.
|
||||
|
||||
## Headers
|
||||
|
||||
```
|
||||
# This is a h1 tag
|
||||
|
||||
## This is a h2 tag
|
||||
|
||||
#### This is a h4 tag
|
||||
```
|
||||
|
||||
# This is a h1 tag
|
||||
|
||||
## This is a h2 tag
|
||||
|
||||
#### This is a h4 tag
|
||||
|
||||
## Emphasis
|
||||
|
||||
```
|
||||
_This text will be italic_
|
||||
|
||||
**This text will be bold**
|
||||
|
||||
_You **can** combine them_
|
||||
```
|
||||
|
||||
_This text will be italic_
|
||||
|
||||
**This text will be bold**
|
||||
|
||||
_You **can** combine them_
|
||||
|
||||
## Lists
|
||||
|
||||
### Unordered
|
||||
|
||||
```
|
||||
- Item 1
|
||||
- Item 2
|
||||
- Item 2a
|
||||
- Item 2b
|
||||
```
|
||||
|
||||
- Item 1
|
||||
- Item 2
|
||||
- Item 2a
|
||||
- Item 2b
|
||||
|
||||
### Ordered
|
||||
|
||||
```
|
||||
1. Item 1
|
||||
1. Item 2
|
||||
1. Item 3
|
||||
1. Item 3a
|
||||
1. Item 3b
|
||||
```
|
||||
|
||||
1. Item 1
|
||||
1. Item 2
|
||||
1. Item 3
|
||||
1. Item 3a
|
||||
1. Item 3b
|
||||
|
||||
## Images
|
||||
|
||||
```
|
||||
|
||||
Format: 
|
||||
```
|
||||
|
||||
|
||||
|
||||
## Links
|
||||
|
||||
```
|
||||
http://github.com - automatic!
|
||||
[GitHub](http://github.com)
|
||||
```
|
||||
|
||||
http://github.com - automatic!
|
||||
[GitHub](http://github.com)
|
||||
|
||||
## Blockquotes
|
||||
|
||||
```
|
||||
As Kanye West said:
|
||||
|
||||
> We're living the future so
|
||||
> the present is our past.
|
||||
```
|
||||
|
||||
As Kanye West said:
|
||||
|
||||
> We're living the future so
|
||||
> the present is our past.
|
||||
|
||||
## Inline code
|
||||
|
||||
```
|
||||
I think you should use an
|
||||
`<addr>` element here instead.
|
||||
```
|
||||
|
||||
I think you should use an
|
||||
`<addr>` element here instead.
|
||||
|
||||
## Syntax highlighting
|
||||
|
||||
Here’s an example of how you can use syntax highlighting with [GitHub Flavored Markdown](https://help.github.com/articles/basic-writing-and-formatting-syntax/):
|
||||
|
||||
````
|
||||
```js:fancyAlert.js
|
||||
function fancyAlert(arg) {
|
||||
if (arg) {
|
||||
$.facebox({ div: '#foo' })
|
||||
}
|
||||
}
|
||||
```
|
||||
````
|
||||
|
||||
And here's how it looks - nicely colored with styled code titles!
|
||||
|
||||
```js:fancyAlert.js
|
||||
function fancyAlert(arg) {
|
||||
if (arg) {
|
||||
$.facebox({ div: '#foo' })
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Footnotes
|
||||
|
||||
```
|
||||
Here is a simple footnote[^1]. With some additional text after it.
|
||||
|
||||
[^1]: My reference.
|
||||
```
|
||||
|
||||
Here is a simple footnote[^1]. With some additional text after it.
|
||||
|
||||
[^1]: My reference.
|
||||
|
||||
## Task Lists
|
||||
|
||||
```
|
||||
- [x] list syntax required (any unordered or ordered list supported)
|
||||
- [x] this is a complete item
|
||||
- [ ] this is an incomplete item
|
||||
```
|
||||
|
||||
- [x] list syntax required (any unordered or ordered list supported)
|
||||
- [x] this is a complete item
|
||||
- [ ] this is an incomplete item
|
||||
|
||||
## Tables
|
||||
|
||||
You can create tables by assembling a list of words and dividing them with hyphens `-` (for the first row), and then separating each column with a pipe `|`:
|
||||
|
||||
```
|
||||
| First Header | Second Header |
|
||||
| --------------------------- | ---------------------------- |
|
||||
| Content from cell 1 | Content from cell 2 |
|
||||
| Content in the first column | Content in the second column |
|
||||
```
|
||||
|
||||
| First Header | Second Header |
|
||||
| --------------------------- | ---------------------------- |
|
||||
| Content from cell 1 | Content from cell 2 |
|
||||
| Content in the first column | Content in the second column |
|
||||
|
||||
## Strikethrough
|
||||
|
||||
Any word wrapped with two tildes (like `~~this~~`) will appear ~~crossed out~~.
|
||||
@ -1,75 +0,0 @@
|
||||
---
|
||||
title: Images in Next.js
|
||||
date: '2020-11-11'
|
||||
tags: ['next js', 'guide']
|
||||
draft: false
|
||||
summary: 'In this article we introduce adding images in the tailwind starter blog and the benefits and limitations of the next/image component.'
|
||||
---
|
||||
|
||||
# Introduction
|
||||
|
||||
The tailwind starter blog has out of the box support for [Next.js's built-in image component](https://nextjs.org/docs/api-reference/next/image) and automatically swaps out default image tags in markdown or mdx documents to use the Image component provided.
|
||||
|
||||
# Usage
|
||||
|
||||
To use in a new page route / javascript file, simply import the image component and call it e.g.
|
||||
|
||||
```js
|
||||
import Image from 'next/image'
|
||||
|
||||
function Home() {
|
||||
return (
|
||||
<>
|
||||
<h1>My Homepage</h1>
|
||||
<Image src="/me.png" alt="Picture of the author" width={500} height={500} />
|
||||
<p>Welcome to my homepage!</p>
|
||||
</>
|
||||
)
|
||||
}
|
||||
|
||||
export default Home
|
||||
```
|
||||
|
||||
For a markdown file, the default image tag can be used and the default `img` tag gets replaced by the `Image` component in the build process.
|
||||
|
||||
Assuming we have a file called `ocean.jpg` in `data/img/ocean.jpg`, the following line of code would generate the optimized image.
|
||||
|
||||
```
|
||||
|
||||
```
|
||||
|
||||
Alternatively, since we are using mdx, we can just use the image component directly! Note, that you would have to provide a fixed width and height. The `img` tag method parses the dimension automatically.
|
||||
|
||||
```js
|
||||
<Image alt="ocean" src="/static/images/ocean.jpg" width={256} height={128} />
|
||||
```
|
||||
|
||||
_Note_: If you try to save the image, it is in webp format, if your browser supports it!
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
Photo by [YUCAR
|
||||
FotoGrafik](https://unsplash.com/@yucar?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText)
|
||||
on
|
||||
[Unsplash](https://unsplash.com/s/photos/sea?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText)
|
||||
</p>
|
||||
|
||||
# Benefits
|
||||
|
||||
- Smaller image size with Webp (~30% smaller than jpeg)
|
||||
- Responsive images - the correct image size is served based on the user's viewport
|
||||
- Lazy loading - images load as they are scrolled to the viewport
|
||||
- Avoids [Cumulative Layout Shift](https://web.dev/cls/)
|
||||
- Optimization on demand instead of build-time - no increase in build time!
|
||||
|
||||
# Limitations
|
||||
|
||||
- Due to the reliance on `next/image`, unless you are using an external image CDN like Cloudinary or Imgix, it is practically required to use Vercel for hosting. This is because the component acts like a serverless function that calls a highly optimized image CDN.
|
||||
|
||||
If you do not want to be tied to Vercel, you can remove `imgToJsx` in `remarkPlugins` in `lib/mdx.js`. This would avoid substituting the default `img` tag.
|
||||
|
||||
Alternatively, one could wait for image optimization at build time to be supported. A different library, [next-optimized-images](https://github.com/cyrilwanner/next-optimized-images) does that, although it requires transforming the images through webpack which is not done here.
|
||||
|
||||
- Images from external links are not passed through `next/image`
|
||||
- All images have to be stored in the `public` folder e.g `/static/images/ocean.jpeg`
|
||||
@ -1,213 +0,0 @@
|
||||
---
|
||||
title: 'Introducing Tailwind Nextjs Starter Blog'
|
||||
date: '2021-01-12'
|
||||
lastmod: '2021-02-01'
|
||||
tags: ['next-js', 'tailwind', 'guide']
|
||||
draft: false
|
||||
summary: 'Looking for a performant, out of the box template, with all the best in web technology to support your blogging needs? Checkout the Tailwind Nextjs Starter Blog template.'
|
||||
images: ['/static/images/canada/mountains.jpg', '/static/images/canada/toronto.jpg']
|
||||
---
|
||||
|
||||
|
||||
|
||||
# Tailwind Nextjs Starter Blog
|
||||
|
||||
[](https://vercel.com/new/git/external?repository-url=https://github.com/timlrx/tailwind-nextjs-starter-blog)
|
||||
|
||||
This is a [Next.js](https://nextjs.org/), [Tailwind CSS](https://tailwindcss.com/) blogging starter template. Probably the most feature-rich Next.js markdown blogging template out there. Comes out of the box configured with the latest technologies to make technical writing a breeze. Easily configurable and customizable. Perfect as a replacement to existing Jekyll and Hugo individual blogs.
|
||||
|
||||
Check out the documentation below to get started.
|
||||
|
||||
Facing issues? Check the [FAQ page](https://github.com/timlrx/tailwind-nextjs-starter-blog/wiki) and do a search on past issues. Feel free to open a new issue if none has been posted previously.
|
||||
|
||||
Feature request? Check the past discussions to see if it has been brought up previously. Otherwise, feel free to start a new discussion thread. All ideas are welcomed!
|
||||
|
||||
## Examples
|
||||
|
||||
- [Demo Blog](https://tailwind-nextjs-starter-blog.vercel.app/) - this repo
|
||||
- [My personal blog](https://www.timlrx.com) - modified to auto-generate blog posts with dates
|
||||
- [Aloisdg's cookbook](https://tambouille.vercel.app/) - with pictures and recipes!
|
||||
- [GautierArcin's demo with next translate](https://tailwind-nextjs-starter-blog-seven.vercel.app/) - includes translation of mdx posts, [source code](https://github.com/GautierArcin/tailwind-nextjs-starter-blog/tree/demo/next-translate)
|
||||
- [David Levai's digital garden](https://davidlevai.com/) - customized design and added email subscriptions
|
||||
- [Thinh's Corner](https://thinhcorner.com/) - [customized layout](https://github.com/Th1nhNg0/th1nhng0.vercel.app/blob/5e73a420828d82f01e7147512a2c3273c4ec19f8/layouts/PostLayout.js) with sticky side table of contents
|
||||
|
||||
Using the template? Feel free to create a PR and add your blog to this list.
|
||||
|
||||
## Motivation
|
||||
|
||||
I wanted to port my existing blog to Nextjs and Tailwind CSS but there was no easy out of the box template to use so I decided to create one. Design is adapted from [Tailwindlabs blog](https://github.com/tailwindlabs/blog.tailwindcss.com).
|
||||
|
||||
I wanted it to be nearly as feature-rich as popular blogging templates like [beautiful-jekyll](https://github.com/daattali/beautiful-jekyll) and [Hugo Academic](https://github.com/wowchemy/wowchemy-hugo-modules) but with the best of React's ecosystem and current web development's best practices.
|
||||
|
||||
## Features
|
||||
|
||||
- Easy styling customization with [Tailwind 3.0](https://tailwindcss.com/blog/tailwindcss-v3) and primary color attribute
|
||||
- Near perfect lighthouse score - [Lighthouse report](https://www.webpagetest.org/result/210111_DiC1_08f3670c3430bf4a9b76fc3b927716c5/)
|
||||
- Lightweight, 45kB first load JS, uses Preact in production build
|
||||
- Mobile-friendly view
|
||||
- Light and dark theme
|
||||
- Self-hosted font with [Fontsource](https://fontsource.org/)
|
||||
- Supports [plausible](https://plausible.io/), [simple analytics](https://simpleanalytics.com/) and google analytics
|
||||
- [MDX - write JSX in markdown documents!](https://mdxjs.com/)
|
||||
- Server-side syntax highlighting with line numbers and line highlighting via [rehype-prism-plus](https://github.com/timlrx/rehype-prism-plus)
|
||||
- Math display supported via [KaTeX](https://katex.org/)
|
||||
- Citation and bibliography support via [rehype-citation](https://github.com/timlrx/rehype-citation)
|
||||
- Automatic image optimization via [next/image](https://nextjs.org/docs/basic-features/image-optimization)
|
||||
- Flexible data retrieval with [mdx-bundler](https://github.com/kentcdodds/mdx-bundler)
|
||||
- Support for tags - each unique tag will be its own page
|
||||
- Support for multiple authors
|
||||
- Blog templates
|
||||
- TOC component
|
||||
- Support for nested routing of blog posts
|
||||
- Newsletter component with support for mailchimp, buttondown, convertkit, klaviyo, revue, and emailoctopus
|
||||
- Supports [giscus](https://github.com/laymonage/giscus), [utterances](https://github.com/utterance/utterances) or disqus
|
||||
- Projects page
|
||||
- Preconfigured security headers
|
||||
- SEO friendly with RSS feed, sitemaps and more!
|
||||
|
||||
## Sample posts
|
||||
|
||||
- [A markdown guide](https://tailwind-nextjs-starter-blog.vercel.app/blog/github-markdown-guide)
|
||||
- [Learn more about images in Next.js](https://tailwind-nextjs-starter-blog.vercel.app/blog/guide-to-using-images-in-nextjs)
|
||||
- [A tour of math typesetting](https://tailwind-nextjs-starter-blog.vercel.app/blog/deriving-ols-estimator)
|
||||
- [Simple MDX image grid](https://tailwind-nextjs-starter-blog.vercel.app/blog/pictures-of-canada)
|
||||
- [Example of long prose](https://tailwind-nextjs-starter-blog.vercel.app/blog/the-time-machine)
|
||||
- [Example of Nested Route Post](https://tailwind-nextjs-starter-blog.vercel.app/blog/nested-route/introducing-multi-part-posts-with-nested-routing)
|
||||
|
||||
## Quick Start Guide
|
||||
|
||||
1. Try installing the starter using the new [Pliny project CLI](https://github.com/timlrx/pliny):
|
||||
|
||||
```bash
|
||||
npm i -g @pliny/cli
|
||||
pliny new --template=starter-blog my-blog
|
||||
```
|
||||
|
||||
It supports the updated version of the blog with Contentlayer, optional choice of TS/JS and different package managers as well as more modularized components which will be the basis of the template going forward.
|
||||
|
||||
Alternatively to stick with the current version, TypeScript and Contentlayer:
|
||||
|
||||
```bash
|
||||
npx degit 'timlrx/tailwind-nextjs-starter-blog#contentlayer'
|
||||
```
|
||||
|
||||
or JS (official support)
|
||||
|
||||
```bash
|
||||
npx degit https://github.com/timlrx/tailwind-nextjs-starter-blog.git
|
||||
```
|
||||
|
||||
2. Personalize `siteMetadata.js` (site related information)
|
||||
3. Modify the content security policy in `next.config.js` if you want to use
|
||||
any analytics provider or a commenting solution other than giscus.
|
||||
4. Personalize `authors/default.md` (main author)
|
||||
5. Modify `projectsData.js`
|
||||
6. Modify `headerNavLinks.js` to customize navigation links
|
||||
7. Add blog posts
|
||||
8. Deploy on Vercel
|
||||
|
||||
## Development
|
||||
|
||||
First, run the development server:
|
||||
|
||||
```bash
|
||||
npm start
|
||||
# or
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
|
||||
|
||||
You can start editing the page by modifying `pages/index.js`. The page auto-updates as you edit the file.
|
||||
|
||||
## Extend / Customize
|
||||
|
||||
`data/siteMetadata.js` - contains most of the site related information which should be modified for a user's need.
|
||||
|
||||
`data/authors/default.md` - default author information (required). Additional authors can be added as files in `data/authors`.
|
||||
|
||||
`data/projectsData.js` - data used to generate styled card on the projects page.
|
||||
|
||||
`data/headerNavLinks.js` - navigation links.
|
||||
|
||||
`data/logo.svg` - replace with your own logo.
|
||||
|
||||
`data/blog` - replace with your own blog posts.
|
||||
|
||||
`public/static` - store assets such as images and favicons.
|
||||
|
||||
`tailwind.config.js` and `css/tailwind.css` - contain the tailwind stylesheet which can be modified to change the overall look and feel of the site.
|
||||
|
||||
`css/prism.css` - controls the styles associated with the code blocks. Feel free to customize it and use your preferred prismjs theme e.g. [prism themes](https://github.com/PrismJS/prism-themes).
|
||||
|
||||
`components/social-icons` - to add other icons, simply copy an svg file from [Simple Icons](https://simpleicons.org/) and map them in `index.js`. Other icons use [heroicons](https://heroicons.com/).
|
||||
|
||||
`components/MDXComponents.js` - pass your own JSX code or React component by specifying it over here. You can then call them directly in the `.mdx` or `.md` file. By default, a custom link and image component is passed.
|
||||
|
||||
`layouts` - main templates used in pages.
|
||||
|
||||
`pages` - pages to route to. Read the [Next.js documentation](https://nextjs.org/docs) for more information.
|
||||
|
||||
`next.config.js` - configuration related to Next.js. You need to adapt the Content Security Policy if you want to load scripts, images etc. from other domains.
|
||||
|
||||
## Post
|
||||
|
||||
### Frontmatter
|
||||
|
||||
Frontmatter follows [Hugo's standards](https://gohugo.io/content-management/front-matter/).
|
||||
|
||||
Currently 7 fields are supported.
|
||||
|
||||
```
|
||||
title (required)
|
||||
date (required)
|
||||
tags (required, can be empty array)
|
||||
lastmod (optional)
|
||||
draft (optional)
|
||||
summary (optional)
|
||||
images (optional, if none provided defaults to socialBanner in siteMetadata config)
|
||||
authors (optional list which should correspond to the file names in `data/authors`. Uses `default` if none is specified)
|
||||
layout (optional list which should correspond to the file names in `data/layouts`)
|
||||
canonicalUrl (optional, canonical url for the post for SEO)
|
||||
```
|
||||
|
||||
Here's an example of a post's frontmatter:
|
||||
|
||||
```
|
||||
---
|
||||
title: 'Introducing Tailwind Nexjs Starter Blog'
|
||||
date: '2021-01-12'
|
||||
lastmod: '2021-01-18'
|
||||
tags: ['next-js', 'tailwind', 'guide']
|
||||
draft: false
|
||||
summary: 'Looking for a performant, out of the box template, with all the best in web technology to support your blogging needs? Checkout the Tailwind Nextjs Starter Blog template.'
|
||||
images: ['/static/images/canada/mountains.jpg', '/static/images/canada/toronto.jpg']
|
||||
authors: ['default', 'sparrowhawk']
|
||||
layout: PostLayout
|
||||
canonicalUrl: https://tailwind-nextjs-starter-blog.vercel.app/blog/introducing-tailwind-nextjs-starter-blog
|
||||
---
|
||||
```
|
||||
|
||||
### Compose
|
||||
|
||||
Run `node ./scripts/compose.js` to bootstrap a new post.
|
||||
|
||||
Follow the interactive prompt to generate a post with pre-filled front matter.
|
||||
|
||||
## Deploy
|
||||
|
||||
**Vercel**
|
||||
The easiest way to deploy the template is to use the [Vercel Platform](https://vercel.com) from the creators of Next.js. Check out the [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details.
|
||||
|
||||
**Netlify / GitHub Pages / Firebase etc.**
|
||||
As the template uses `next/image` for image optimization, additional configurations have to be made to deploy on other popular static hosting websites like [Netlify](https://www.netlify.com/) or [GitHub Pages](https://pages.github.com/). An alternative image optimization provider such as Imgix, Cloudinary or Akamai has to be used. Alternatively, replace the `next/image` component with a standard `<img>` tag. See [`next/image` documentation](https://nextjs.org/docs/basic-features/image-optimization) for more details.
|
||||
|
||||
The API routes used in the newsletter component cannot be used in a static site export. You will need to use a form API endpoint provider and substitute the route in the newsletter component accordingly. Other hosting platforms such as Netlify also offer alternative solutions - please refer to their docs for more information.
|
||||
|
||||
## Support
|
||||
|
||||
Using the template? Support this effort by giving a star on GitHub, sharing your own blog and giving a shoutout on Twitter or be a project [sponsor](https://github.com/sponsors/timlrx).
|
||||
|
||||
## Licence
|
||||
|
||||
[MIT](https://github.com/timlrx/tailwind-nextjs-starter-blog/blob/master/LICENSE) © [Timothy Lin](https://www.timrlx.com)
|
||||
@ -1,10 +0,0 @@
|
||||
---
|
||||
title: My fancy title
|
||||
date: '2021-01-31'
|
||||
tags: ['hello']
|
||||
draft: true
|
||||
summary:
|
||||
images: []
|
||||
---
|
||||
|
||||
Draft post which should not display
|
||||
@ -1,30 +0,0 @@
|
||||
---
|
||||
title: Introducing Multi-part Posts with Nested Routing
|
||||
date: '2021-05-02'
|
||||
tags: ['multi-author', 'next-js', 'feature']
|
||||
draft: false
|
||||
summary: 'The blog template supports posts in nested sub-folders. This can be used to group posts of similar content e.g. a multi-part course. This post is itself an example of a nested route!'
|
||||
---
|
||||
|
||||
# Nested Routes
|
||||
|
||||
The blog template supports posts in nested sub-folders. This helps in organisation and can be used to group posts of similar content e.g. a multi-part series. This post is itself an example of a nested route! It's located in the `/data/blog/nested-route` folder.
|
||||
|
||||
## How
|
||||
|
||||
Simplify create multiple folders inside the main `/data/blog` folder and add your `.md`/`.mdx` files to them. You can even create something like `/data/blog/nested-route/deeply-nested-route/my-post.md`
|
||||
|
||||
We use Next.js catch all routes to handle the routing and path creations.
|
||||
|
||||
## Use Cases
|
||||
|
||||
Here are some reasons to use nested routes
|
||||
|
||||
- More logical content organisation (blogs will still be displayed based on the created date)
|
||||
- Multi-part posts
|
||||
- Different sub-routes for each author
|
||||
- Internationalization (though it would be recommended to use [Next.js built-in i8n routing](https://nextjs.org/docs/advanced-features/i18n-routing))
|
||||
|
||||
## Note
|
||||
|
||||
- The previous/next post links at bottom of the template are currently sorted by date. One could explore modifying the template to refer the reader to the previous/next post in the series, rather than by date.
|
||||
@ -1,451 +0,0 @@
|
||||
---
|
||||
title: 'New features in v1'
|
||||
date: 2021-08-07T15:32:14Z
|
||||
lastmod: '2021-02-01'
|
||||
tags: ['next-js', 'tailwind', 'guide']
|
||||
draft: false
|
||||
summary: 'An overview of the new features released in v1 - code block copy, multiple authors, frontmatter layout and more'
|
||||
layout: PostSimple
|
||||
bibliography: references-data.bib
|
||||
canonicalUrl: https://tailwind-nextjs-starter-blog.vercel.app/blog/new-features-in-v1/
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
A post on the new features introduced in v1.0. New features:
|
||||
|
||||
<TOCInline toc={props.toc} exclude="Overview" toHeading={2} />
|
||||
|
||||
First load JS decreased from 43kB to 39kB despite all the new features added!^[With the new changes in Nextjs 12, first load JS increase to 45kB.]
|
||||
|
||||
See [upgrade guide](#upgrade-guide) below if you are migrating from v0 version of the template.
|
||||
|
||||
## Theme colors
|
||||
|
||||
You can easily modify the theme color by changing the primary attribute in the tailwind config file:
|
||||
|
||||
```js:tailwind.config.js
|
||||
theme: {
|
||||
colors: {
|
||||
primary: colors.teal,
|
||||
gray: colors.neutral,
|
||||
...
|
||||
}
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
The primary color attribute should be assigned an object with keys from 50, 100, 200 ... 900 and the corresponding color code values.
|
||||
|
||||
Tailwind includes great default color palettes that can be used for theming your own website. Check out [customizing colors documentation page](https://tailwindcss.com/docs/customizing-colors) for the full range of options.
|
||||
|
||||
Migrating from v1? You can revert to the previous theme by setting `primary` to `colors.sky` (Tailwind 2.2.2 and above, otherwise `colors.lightBlue`) and changing gray to `colors.gray`.
|
||||
|
||||
From v1.1.2+, you can also customize the style of your code blocks easily by modifying the `css/prism.css` stylesheet. Token classnames are compatible with prismjs
|
||||
so you can copy and adapt token styles from a prismjs stylesheet e.g. [prism themes](https://github.com/PrismJS/prism-themes).
|
||||
|
||||
## Xdm MDX compiler
|
||||
|
||||
We switched the MDX bundler from [next-mdx-remote](https://github.com/hashicorp/next-mdx-remote) to [mdx-bundler](https://github.com/kentcdodds/mdx-bundler).
|
||||
This uses [xdm](https://github.com/wooorm/xdm) under the hood, the latest micromark 3 and remark, rehype libraries.
|
||||
|
||||
**Warning:** If you were using custom remark or rehype libraries, please upgrade to micromark 3 compatible ones. If you are upgrading, please delete `node_modules` and `package-lock.json` to avoid having past dependencies related issues.
|
||||
|
||||
[xdm](https://github.com/wooorm/xdm) contains multiple improvements over [@mdx-js/mdx](https://github.com/mdx-js/mdx), the compiler used internally by next-mdx-remote, but there might be some breaking behaviour changes.
|
||||
Please check your markdown output to verify.
|
||||
|
||||
Some new possibilities include loading components directly in the mdx file using the import syntax and including js code which could be compiled and bundled at the build step.
|
||||
|
||||
For example, the following jsx snippet can be used directly in an MDX file to render the page title component:
|
||||
|
||||
```jsx
|
||||
import PageTitle from './PageTitle.js'
|
||||
;<PageTitle> Using JSX components in MDX </PageTitle>
|
||||
```
|
||||
|
||||
import PageTitle from './PageTitle.js'
|
||||
|
||||
<PageTitle> Using JSX components in MDX </PageTitle>
|
||||
|
||||
The default configuration resolves all components relative to the `components` directory.
|
||||
|
||||
**Note**:
|
||||
Components which require external image loaders also require additional esbuild configuration.
|
||||
Components which are dependent on global application state on lifecycle like the Nextjs `Link` component would also not work with this setup as each mdx file is built independently.
|
||||
For such cases, it is better to use component substitution.
|
||||
|
||||
## Table of contents component
|
||||
|
||||
Inspired by [Docusaurus](https://docusaurus.io/docs/next/markdown-features/inline-toc) and Gatsby's [gatsby-remark-table-of-contents](https://www.gatsbyjs.com/plugins/gatsby-remark-table-of-contents/),
|
||||
the `toc` variable containing all the top level headings of the document is passed to the MDX file and can be styled accordingly.
|
||||
To make generating a table of contents (TOC) simple, you can use the existing `TOCInline` component.
|
||||
|
||||
For example, the TOC in this post was generated with the following code:
|
||||
|
||||
```jsx
|
||||
<TOCInline toc={props.toc} exclude="Overview" toHeading={2} />
|
||||
```
|
||||
|
||||
You can customise the headings that are displayed by configuring the `fromHeading` and `toHeading` props, or exclude particular headings
|
||||
by passing a string or a string array to the `exclude` prop. By default, all headings that are of depth 3 or smaller are indented. This can be configured by changing the `indentDepth` property.
|
||||
A `asDisclosure` prop can be used to render the TOC within an expandable disclosure element.
|
||||
|
||||
Here's the full TOC rendered in a disclosure element.
|
||||
|
||||
```jsx
|
||||
<TOCInline toc={props.toc} asDisclosure />
|
||||
```
|
||||
|
||||
<TOCInline toc={props.toc} asDisclosure />
|
||||
|
||||
## Layouts
|
||||
|
||||
You can map mdx blog content to layout components by configuring the frontmatter field. For example, this post is written with the new `PostSimple` layout!
|
||||
|
||||
### Adding new templates
|
||||
|
||||
layout templates are stored in the `./layouts` folder. You can add your React components that you want to map to markdown content in this folder.
|
||||
The component file name must match that specified in the markdown frontmatter `layout` field.
|
||||
|
||||
The only required field is `children` which contains the rendered MDX content, though you would probably want to pass in the frontMatter contents and render it in the template.
|
||||
|
||||
You can configure the template to take in other fields - see `PostLayout` component for an example.
|
||||
|
||||
Here's an example layout which you can further customise:
|
||||
|
||||
```jsx
|
||||
export default function ExampleLayout({ frontMatter, children }) {
|
||||
const { date, title } = frontMatter
|
||||
|
||||
return (
|
||||
<SectionContainer>
|
||||
<div>{date}</div>
|
||||
<h1>{title}</h1>
|
||||
<div>{children}</div>
|
||||
</SectionContainer>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### Configuring a blog post frontmatter
|
||||
|
||||
Use the `layout` frontmatter field to specify the template you want to map the markdown post to. Here's how the frontmatter of this post looks like:
|
||||
|
||||
```
|
||||
---
|
||||
title: 'New features in v1'
|
||||
date: '2021-05-26 '
|
||||
tags: ['next-js', 'tailwind', 'guide']
|
||||
draft: false
|
||||
summary: 'Introducing the new layout features - you can map mdx blog content to layout components by configuring the frontmatter field'
|
||||
layout: PostSimple
|
||||
---
|
||||
```
|
||||
|
||||
You can configure the default layout in the respective page section by modifying the `DEFAULT_LAYOUT` variable.
|
||||
The `DEFAULT_LAYOUT` for blog posts page is set to `PostLayout`.
|
||||
|
||||
### Extend
|
||||
|
||||
`layout` is mapped to wrapper which wraps the entire MDX content.
|
||||
|
||||
```jsx
|
||||
export const MDXComponents = {
|
||||
Image,
|
||||
a: CustomLink,
|
||||
pre: Pre,
|
||||
wrapper: ({ components, layout, ...rest }) => {
|
||||
const Layout = require(`../layouts/${layout}`).default
|
||||
return <Layout {...rest} />
|
||||
},
|
||||
}
|
||||
|
||||
export const MDXLayoutRenderer = ({ layout, mdxSource, ...rest }) => {
|
||||
const MDXLayout = useMemo(() => getMDXComponent(mdxSource), [mdxSource])
|
||||
|
||||
return <MDXLayout layout={layout} components={MDXComponents} {...rest} />
|
||||
}
|
||||
```
|
||||
|
||||
Use the `MDXLayoutRenderer` component on a page where you want to accept a layout name to map to the desired layout.
|
||||
You need to pass the layout name from the layout folder (it has to be an exact match).
|
||||
|
||||
## Analytics
|
||||
|
||||
The template now supports [plausible](https://plausible.io/), [simple analytics](https://simpleanalytics.com/) and google analytics.
|
||||
Configure `siteMetadata.js` with the settings that correspond with the desired analytics provider.
|
||||
|
||||
```js
|
||||
analytics: {
|
||||
// supports plausible, simpleAnalytics or googleAnalytics
|
||||
plausibleDataDomain: '', // e.g. tailwind-nextjs-starter-blog.vercel.app
|
||||
simpleAnalytics: false, // true or false
|
||||
googleAnalyticsId: '', // e.g. UA-000000-2 or G-XXXXXXX
|
||||
},
|
||||
```
|
||||
|
||||
Custom events are also supported. You can import the `logEvent` function from `@components/analytics/[ANALYTICS-PROVIDER]` file and call it when
|
||||
triggering certain events of interest. _Note_: Additional configuration might be required depending on the analytics provider, please check their official
|
||||
documentation for more information.
|
||||
|
||||
## Blog comments system
|
||||
|
||||
We have also added support for [giscus](https://github.com/laymonage/giscus), [utterances](https://github.com/utterance/utterances) or disqus.
|
||||
To enable, simply configure `siteMetadata.js` comments property with the desired provider and settings as specified in the config file.
|
||||
|
||||
```js
|
||||
comment: {
|
||||
// Select a provider and use the environment variables associated to it
|
||||
// https://vercel.com/docs/environment-variables
|
||||
provider: 'giscus', // supported providers: giscus, utterances, disqus
|
||||
giscusConfig: {
|
||||
// Visit the link below, and follow the steps in the 'configuration' section
|
||||
// https://giscus.app/
|
||||
repo: process.env.NEXT_PUBLIC_GISCUS_REPO,
|
||||
repositoryId: process.env.NEXT_PUBLIC_GISCUS_REPOSITORY_ID,
|
||||
category: process.env.NEXT_PUBLIC_GISCUS_CATEGORY,
|
||||
categoryId: process.env.NEXT_PUBLIC_GISCUS_CATEGORY_ID,
|
||||
mapping: 'pathname', // supported options: pathname, url, title
|
||||
reactions: '1', // Emoji reactions: 1 = enable / 0 = disable
|
||||
// Send discussion metadata periodically to the parent window: 1 = enable / 0 = disable
|
||||
metadata: '0',
|
||||
// theme example: light, dark, dark_dimmed, dark_high_contrast
|
||||
// transparent_dark, preferred_color_scheme, custom
|
||||
theme: 'light',
|
||||
// theme when dark mode
|
||||
darkTheme: 'transparent_dark',
|
||||
// If the theme option above is set to 'custom`
|
||||
// please provide a link below to your custom theme css file.
|
||||
// example: https://giscus.app/themes/custom_example.css
|
||||
themeURL: '',
|
||||
},
|
||||
utterancesConfig: {
|
||||
// Visit the link below, and follow the steps in the 'configuration' section
|
||||
// https://utteranc.es/
|
||||
repo: process.env.NEXT_PUBLIC_UTTERANCES_REPO,
|
||||
issueTerm: '', // supported options: pathname, url, title
|
||||
label: '', // label (optional): Comment 💬
|
||||
// theme example: github-light, github-dark, preferred-color-scheme
|
||||
// github-dark-orange, icy-dark, dark-blue, photon-dark, boxy-light
|
||||
theme: '',
|
||||
// theme when dark mode
|
||||
darkTheme: '',
|
||||
},
|
||||
disqus: {
|
||||
// https://help.disqus.com/en/articles/1717111-what-s-a-shortname
|
||||
shortname: process.env.NEXT_PUBLIC_DISQUS_SHORTNAME,
|
||||
},
|
||||
},
|
||||
```
|
||||
|
||||
## Multiple authors
|
||||
|
||||
Information on authors is now split from `siteMetadata.js` and stored in its own `data/authors` folder as a markdown file. Minimally, you will need to have a `default.md` file with authorship information. You can create additional files as required and the file name will be used as the reference to the author.
|
||||
|
||||
Here's how an author markdown file might look like:
|
||||
|
||||
```md:default.md
|
||||
---
|
||||
name: Tails Azimuth
|
||||
avatar: /static/images/avatar.png
|
||||
occupation: Professor of Atmospheric Science
|
||||
company: Stanford University
|
||||
email: address@yoursite.com
|
||||
twitter: https://twitter.com/Twitter
|
||||
linkedin: https://www.linkedin.com
|
||||
github: https://github.com
|
||||
---
|
||||
|
||||
A long description of yourself...
|
||||
```
|
||||
|
||||
You can use this information in multiple places across the template. For example in the about section of the page, we grab the default author information with this line of code:
|
||||
|
||||
```js
|
||||
const authorDetails = await getFileBySlug('authors', ['default'])
|
||||
```
|
||||
|
||||
This is rendered in the `AuthorLayout` template.
|
||||
|
||||
### Multiple authors in blog post
|
||||
|
||||
The frontmatter of a blog post accepts an optional `authors` array field. If no field is specified, it is assumed that the default author is used. Simply pass in an array of authors to render multiple authors associated with a post.
|
||||
|
||||
For example, the following frontmatter will display the authors given by `data/authors/default.md` and `data/authors/sparrowhawk.md`
|
||||
|
||||
```yaml
|
||||
title: 'My first post'
|
||||
date: '2021-01-12'
|
||||
draft: false
|
||||
summary: 'My first post'
|
||||
authors: ['default', 'sparrowhawk']
|
||||
```
|
||||
|
||||
A demo of a multiple authors post is shown in [Introducing Tailwind Nextjs Starter Blog post](/blog/introducing-tailwind-nextjs-starter-blog).
|
||||
|
||||
## Copy button for code blocks
|
||||
|
||||
Hover over a code block and you will notice a GitHub-inspired copy button! You can modify `./components/Pre.js` to further customise it.
|
||||
The component is passed to `MDXComponents` and modifies all `<pre>` blocks.
|
||||
|
||||
## Line highlighting and line numbers
|
||||
|
||||
Line highlighting and line numbers are now supported out of the box thanks to the new [rehype-prism-plus plugin](https://github.com/timlrx/rehype-prism-plus)
|
||||
|
||||
The following javascript code block:
|
||||
|
||||
````
|
||||
```js {1, 3-4} showLineNumbers
|
||||
var num1, num2, sum
|
||||
num1 = prompt('Enter first number')
|
||||
num2 = prompt('Enter second number')
|
||||
sum = parseInt(num1) + parseInt(num2) // "+" means "add"
|
||||
alert('Sum = ' + sum) // "+" means combine into a string
|
||||
```
|
||||
````
|
||||
|
||||
will appear as:
|
||||
|
||||
```js {1,3-4} showLineNumbers
|
||||
var num1, num2, sum
|
||||
num1 = prompt('Enter first number')
|
||||
num2 = prompt('Enter second number')
|
||||
sum = parseInt(num1) + parseInt(num2) // "+" means "add"
|
||||
alert('Sum = ' + sum) // "+" means combine into a string
|
||||
```
|
||||
|
||||
To modify the styles, change the following class selectors in the `prism.css` file:
|
||||
|
||||
```css
|
||||
.code-highlight {
|
||||
@apply float-left min-w-full;
|
||||
}
|
||||
|
||||
.code-line {
|
||||
@apply -mx-4 block border-l-4 border-opacity-0 pl-4 pr-4;
|
||||
}
|
||||
|
||||
.code-line.inserted {
|
||||
@apply bg-green-500 bg-opacity-20;
|
||||
}
|
||||
|
||||
.code-line.deleted {
|
||||
@apply bg-red-500 bg-opacity-20;
|
||||
}
|
||||
|
||||
.highlight-line {
|
||||
@apply -mx-4 border-l-4 border-primary-500 bg-gray-700 bg-opacity-50;
|
||||
}
|
||||
|
||||
.line-number::before {
|
||||
@apply mr-4 -ml-2 inline-block w-4 text-right text-gray-400;
|
||||
content: attr(line);
|
||||
}
|
||||
```
|
||||
|
||||
## Newletter component (v1.1.3)
|
||||
|
||||
Introduced in v1.1.3, the newsletter component gives you an easy way to build an audience. It integrates with the following providers:
|
||||
|
||||
- [Mailchimp](https://mailchimp.com/)
|
||||
- [Buttondown](https://buttondown.email/)
|
||||
- [Convertkit](https://convertkit.com/)
|
||||
|
||||
To use it, specify the provider which you are using in the config file and add the necessary environment variables to the `.env` file.
|
||||
For more information on the required variables, check out `.env.sample.`
|
||||
|
||||
Two components are exported, a default `NewsletterForm` and a `BlogNewsletterForm` component, which is also passed in as an MDX component
|
||||
and can be used in a blog post:
|
||||
|
||||
```jsx
|
||||
<BlogNewsletterForm title="Like what you are reading?" />
|
||||
```
|
||||
|
||||
<BlogNewsletterForm title="Like what you are reading?" />
|
||||
|
||||
The component relies on nextjs's [API routes](https://nextjs.org/docs/api-routes/introduction) which requires a server-side instance of nextjs to be setup
|
||||
and is not compatible with a 100% static site export. Users should either self-host or use a compatible platform like Vercel or Netlify which supports this functionality.
|
||||
|
||||
A static site compatible alternative is to substitute the route in the newsletter component with a form API endpoint provider.
|
||||
|
||||
## Bibliography and Citations (v1.2.1)
|
||||
|
||||
`rehype-citation` plugin is added to the xdm processing pipeline in v1.2.1. This allows you to easily format citations and insert bibliography from an existing bibtex or CSL-json file.
|
||||
|
||||
For example, the following markdown code sample:
|
||||
|
||||
```md
|
||||
Standard citation [@Nash1950]
|
||||
In-text citations e.g. @Nash1951
|
||||
Multiple citations [see @Nash1950; @Nash1951, page 50]
|
||||
|
||||
**References:**
|
||||
|
||||
[^ref]
|
||||
```
|
||||
|
||||
is rendered to the following:
|
||||
|
||||
Standard citation [@Nash1950]
|
||||
In-text citations e.g. @Nash1951
|
||||
Multiple citations [see @Nash1950; @Nash1951, page 50]
|
||||
|
||||
**References:**
|
||||
|
||||
[^ref]
|
||||
|
||||
A bibliography will be inserted at the end of the document, but this can be overwritten by specifying a `[^Ref]` tag at the intended location.
|
||||
The plugin uses APA citation formation, but also supports the following CSLs, 'apa', 'vancouver', 'harvard1', 'chicago', 'mla', or a path to a user-specified CSL file.
|
||||
|
||||
See [rehype-citation readme](https://github.com/timlrx/rehype-citation) for more information on the configuration options.
|
||||
|
||||
## Self-hosted font (v1.5.0)
|
||||
|
||||
Google font has been replaced with self-hosted font from [Fontsource](https://fontsource.org/). This gives the following [advantages](https://fontsource.org/docs/introduction):
|
||||
|
||||
> Self-hosting brings significant performance gains as loading fonts from hosted services, such as Google Fonts, lead to an extra (render blocking) network request. To provide perspective, for simple websites it has been seen to double visual load times.
|
||||
>
|
||||
> Fonts remain version locked. Google often pushes updates to their fonts without notice, which may interfere with your live production projects. Manage your fonts like any other NPM dependency.
|
||||
>
|
||||
> Commit to privacy. Google does track the usage of their fonts and for those who are extremely privacy concerned, self-hosting is an alternative.
|
||||
|
||||
This leads to a smaller font bundle and a 0.1s faster load time ([webpagetest comparison](https://www.webpagetest.org/video/compare.php?tests=220201_AiDcFH_f68a69b758454dd52d8e67493fdef7da,220201_BiDcMC_bf2d53f14483814ba61e794311dfa771)).
|
||||
|
||||
To change the default Inter font:
|
||||
|
||||
1. Install the preferred [font](https://fontsource.org/fonts) - `npm install -save @fontsource/<font-name>`
|
||||
2. Update the import at `pages/_app.js`- `import '@fontsource/<font-name>.css'`
|
||||
3. Update the `fontfamily` property in the tailwind css config file
|
||||
|
||||
## Upgrade guide
|
||||
|
||||
There are significant portions of the code that has been changed from v0 to v1 including support for layouts and a new mdx engine.
|
||||
|
||||
There's also no real reason to change if the previous one serves your needs and it might be easier to copy
|
||||
the component changes you are interested in to your existing blog rather than migrating everything over.
|
||||
|
||||
Nonetheless, if you want to do so and have not changed much of the template, you could clone the new version and copy over the blog post over to the new template.
|
||||
|
||||
Another alternative would be to pull the latest template version with the following code:
|
||||
|
||||
```bash
|
||||
git remote add template git@github.com:timlrx/tailwind-nextjs-starter-blog.git
|
||||
git pull template v1 --allow-unrelated-histories
|
||||
rm -rf node_modules
|
||||
```
|
||||
|
||||
You can see an example of such a migration in this [commit](https://github.com/timlrx/timlrx.com/commit/bba1c185384fd6d5cdaac15abf802fdcff027286) for my personal blog.
|
||||
|
||||
v1 also uses `feed.xml` rather than `index.xml`, to avoid some build issues with Vercel. If you are migrating you should add a redirect to `next.config.js` like so:
|
||||
|
||||
```js
|
||||
async redirects() {
|
||||
return [
|
||||
{
|
||||
source: '/:path/index.xml',
|
||||
destination: '/:path/feed.xml',
|
||||
permanent: true,
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
@ -1,82 +0,0 @@
|
||||
---
|
||||
title: O Canada
|
||||
date: '2017-07-15'
|
||||
tags: ['holiday', 'canada', 'images']
|
||||
draft: false
|
||||
summary: The scenic lands of Canada featuring maple leaves, snow-capped mountains, turquoise lakes and Toronto. Take in the sights in this photo gallery exhibition and see how easy it is to replicate with some MDX magic and tailwind classes.
|
||||
---
|
||||
|
||||
# O Canada
|
||||
|
||||
The scenic lands of Canada featuring maple leaves, snow-capped mountains, turquoise lakes and Toronto. Take in the sights in this photo gallery exhibition and see how easy it is to replicate with some MDX magic and tailwind classes.
|
||||
|
||||
Features images served using `next/image` component. The locally stored images are located in a folder with the following path: `/static/images/canada/[filename].jpg`
|
||||
|
||||
Since we are using mdx, we can create a simple responsive flexbox grid to display our images with a few tailwind css classes.
|
||||
|
||||
---
|
||||
|
||||
# Gallery
|
||||
|
||||
<div className="flex flex-wrap -mx-2 overflow-hidden xl:-mx-2">
|
||||
<div className="my-1 px-2 w-full overflow-hidden xl:my-1 xl:px-2 xl:w-1/2">
|
||||
|
||||
</div>
|
||||
<div className="my-1 px-2 w-full overflow-hidden xl:my-1 xl:px-2 xl:w-1/2">
|
||||
|
||||
</div>
|
||||
<div className="my-1 px-2 w-full overflow-hidden xl:my-1 xl:px-2 xl:w-1/2">
|
||||
|
||||
</div>
|
||||
<div className="my-1 px-2 w-full overflow-hidden xl:my-1 xl:px-2 xl:w-1/2">
|
||||
|
||||
</div>
|
||||
</div>
|
||||
|
||||
# Implementation
|
||||
|
||||
```js
|
||||
<div className="flex flex-wrap -mx-2 overflow-hidden xl:-mx-2">
|
||||
<div className="my-1 px-2 w-full overflow-hidden xl:my-1 xl:px-2 xl:w-1/2">
|
||||
|
||||
</div>
|
||||
<div className="my-1 px-2 w-full overflow-hidden xl:my-1 xl:px-2 xl:w-1/2">
|
||||
|
||||
</div>
|
||||
<div className="my-1 px-2 w-full overflow-hidden xl:my-1 xl:px-2 xl:w-1/2">
|
||||
|
||||
</div>
|
||||
<div className="my-1 px-2 w-full overflow-hidden xl:my-1 xl:px-2 xl:w-1/2">
|
||||
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
With MDX v2, one can interleave markdown in jsx as shown in the example code.
|
||||
|
||||
### Photo Credits
|
||||
|
||||
<div>
|
||||
Maple photo by [Guillaume
|
||||
Jaillet](https://unsplash.com/@i_am_g?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText)
|
||||
on
|
||||
[Unsplash](https://unsplash.com/s/photos/canada?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText)
|
||||
</div>
|
||||
<div>
|
||||
Mountains photo by [John
|
||||
Lee](https://unsplash.com/@john_artifexfilms?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText)
|
||||
on
|
||||
[Unsplash](https://unsplash.com/s/photos/canada?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText)
|
||||
</div>
|
||||
<div>
|
||||
Lake photo by [Tj
|
||||
Holowaychuk](https://unsplash.com/@tjholowaychuk?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText)
|
||||
on
|
||||
[Unsplash](https://unsplash.com/s/photos/canada?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText)
|
||||
</div>
|
||||
<div>
|
||||
Toronto photo by [Matthew
|
||||
Henry](https://unsplash.com/@matthewhenry?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText)
|
||||
on
|
||||
[Unsplash](https://unsplash.com/s/photos/canada?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText)
|
||||
</div>
|
||||
@ -1,238 +0,0 @@
|
||||
---
|
||||
title: 'The Time Machine'
|
||||
date: '2018-08-15'
|
||||
tags: ['writings', 'book', 'reflection']
|
||||
draft: false
|
||||
summary: 'The Time Traveller (for so it will be convenient to speak of him) was
|
||||
expounding a recondite matter to us. His pale grey eyes shone and
|
||||
twinkled, and his usually pale face was flushed and animated...'
|
||||
---
|
||||
|
||||
# The Time Machine by H. G. Wells
|
||||
|
||||
_Title_: The Time Machine
|
||||
|
||||
_Author_: H. G. Wells
|
||||
|
||||
_Subject_: Science Fiction
|
||||
|
||||
_Language_: English
|
||||
|
||||
_Source_: [Project Gutenberg](https://www.gutenberg.org/ebooks/35)
|
||||
|
||||
## Introduction
|
||||
|
||||
The Time Traveller (for so it will be convenient to speak of him) was
|
||||
expounding a recondite matter to us. His pale grey eyes shone and
|
||||
twinkled, and his usually pale face was flushed and animated. The fire
|
||||
burnt brightly, and the soft radiance of the incandescent lights in the
|
||||
lilies of silver caught the bubbles that flashed and passed in our
|
||||
glasses. Our chairs, being his patents, embraced and caressed us rather
|
||||
than submitted to be sat upon, and there was that luxurious
|
||||
after-dinner atmosphere, when thought runs gracefully free of the
|
||||
trammels of precision. And he put it to us in this way—marking the
|
||||
points with a lean forefinger—as we sat and lazily admired his
|
||||
earnestness over this new paradox (as we thought it) and his fecundity.
|
||||
|
||||
“You must follow me carefully. I shall have to controvert one or two
|
||||
ideas that are almost universally accepted. The geometry, for instance,
|
||||
they taught you at school is founded on a misconception.”
|
||||
|
||||
“Is not that rather a large thing to expect us to begin upon?” said
|
||||
Filby, an argumentative person with red hair.
|
||||
|
||||
“I do not mean to ask you to accept anything without reasonable ground
|
||||
for it. You will soon admit as much as I need from you. You know of
|
||||
course that a mathematical line, a line of thickness _nil_, has no real
|
||||
existence. They taught you that? Neither has a mathematical plane.
|
||||
These things are mere abstractions.”
|
||||
|
||||
“That is all right,” said the Psychologist.
|
||||
|
||||
“Nor, having only length, breadth, and thickness, can a cube have a
|
||||
real existence.”
|
||||
|
||||
“There I object,” said Filby. “Of course a solid body may exist. All
|
||||
real things—”
|
||||
|
||||
“So most people think. But wait a moment. Can an _instantaneous_ cube
|
||||
exist?”
|
||||
|
||||
“Don’t follow you,” said Filby.
|
||||
|
||||
“Can a cube that does not last for any time at all, have a real
|
||||
existence?”
|
||||
|
||||
Filby became pensive. “Clearly,” the Time Traveller proceeded, “any
|
||||
real body must have extension in _four_ directions: it must have
|
||||
Length, Breadth, Thickness, and—Duration. But through a natural
|
||||
infirmity of the flesh, which I will explain to you in a moment, we
|
||||
incline to overlook this fact. There are really four dimensions, three
|
||||
which we call the three planes of Space, and a fourth, Time. There is,
|
||||
however, a tendency to draw an unreal distinction between the former
|
||||
three dimensions and the latter, because it happens that our
|
||||
consciousness moves intermittently in one direction along the latter
|
||||
from the beginning to the end of our lives.”
|
||||
|
||||
“That,” said a very young man, making spasmodic efforts to relight his
|
||||
cigar over the lamp; “that . . . very clear indeed.”
|
||||
|
||||
“Now, it is very remarkable that this is so extensively overlooked,”
|
||||
continued the Time Traveller, with a slight accession of cheerfulness.
|
||||
“Really this is what is meant by the Fourth Dimension, though some
|
||||
people who talk about the Fourth Dimension do not know they mean it. It
|
||||
is only another way of looking at Time. _There is no difference between
|
||||
Time and any of the three dimensions of Space except that our
|
||||
consciousness moves along it_. But some foolish people have got hold of
|
||||
the wrong side of that idea. You have all heard what they have to say
|
||||
about this Fourth Dimension?”
|
||||
|
||||
“_I_ have not,” said the Provincial Mayor.
|
||||
|
||||
“It is simply this. That Space, as our mathematicians have it, is
|
||||
spoken of as having three dimensions, which one may call Length,
|
||||
Breadth, and Thickness, and is always definable by reference to three
|
||||
planes, each at right angles to the others. But some philosophical
|
||||
people have been asking why _three_ dimensions particularly—why not
|
||||
another direction at right angles to the other three?—and have even
|
||||
tried to construct a Four-Dimensional geometry. Professor Simon Newcomb
|
||||
was expounding this to the New York Mathematical Society only a month
|
||||
or so ago. You know how on a flat surface, which has only two
|
||||
dimensions, we can represent a figure of a three-dimensional solid, and
|
||||
similarly they think that by models of three dimensions they could
|
||||
represent one of four—if they could master the perspective of the
|
||||
thing. See?”
|
||||
|
||||
“I think so,” murmured the Provincial Mayor; and, knitting his brows,
|
||||
he lapsed into an introspective state, his lips moving as one who
|
||||
repeats mystic words. “Yes, I think I see it now,” he said after some
|
||||
time, brightening in a quite transitory manner.
|
||||
|
||||
“Well, I do not mind telling you I have been at work upon this geometry
|
||||
of Four Dimensions for some time. Some of my results are curious. For
|
||||
instance, here is a portrait of a man at eight years old, another at
|
||||
fifteen, another at seventeen, another at twenty-three, and so on. All
|
||||
these are evidently sections, as it were, Three-Dimensional
|
||||
representations of his Four-Dimensioned being, which is a fixed and
|
||||
unalterable thing.
|
||||
|
||||
“Scientific people,” proceeded the Time Traveller, after the pause
|
||||
required for the proper assimilation of this, “know very well that Time
|
||||
is only a kind of Space. Here is a popular scientific diagram, a
|
||||
weather record. This line I trace with my finger shows the movement of
|
||||
the barometer. Yesterday it was so high, yesterday night it fell, then
|
||||
this morning it rose again, and so gently upward to here. Surely the
|
||||
mercury did not trace this line in any of the dimensions of Space
|
||||
generally recognised? But certainly it traced such a line, and that
|
||||
line, therefore, we must conclude, was along the Time-Dimension.”
|
||||
|
||||
“But,” said the Medical Man, staring hard at a coal in the fire, “if
|
||||
Time is really only a fourth dimension of Space, why is it, and why has
|
||||
it always been, regarded as something different? And why cannot we move
|
||||
in Time as we move about in the other dimensions of Space?”
|
||||
|
||||
The Time Traveller smiled. “Are you so sure we can move freely in
|
||||
Space? Right and left we can go, backward and forward freely enough,
|
||||
and men always have done so. I admit we move freely in two dimensions.
|
||||
But how about up and down? Gravitation limits us there.”
|
||||
|
||||
“Not exactly,” said the Medical Man. “There are balloons.”
|
||||
|
||||
“But before the balloons, save for spasmodic jumping and the
|
||||
inequalities of the surface, man had no freedom of vertical movement.”
|
||||
|
||||
“Still they could move a little up and down,” said the Medical Man.
|
||||
|
||||
“Easier, far easier down than up.”
|
||||
|
||||
“And you cannot move at all in Time, you cannot get away from the
|
||||
present moment.”
|
||||
|
||||
“My dear sir, that is just where you are wrong. That is just where the
|
||||
whole world has gone wrong. We are always getting away from the present
|
||||
moment. Our mental existences, which are immaterial and have no
|
||||
dimensions, are passing along the Time-Dimension with a uniform
|
||||
velocity from the cradle to the grave. Just as we should travel _down_
|
||||
if we began our existence fifty miles above the earth’s surface.”
|
||||
|
||||
“But the great difficulty is this,” interrupted the Psychologist. ’You
|
||||
_can_ move about in all directions of Space, but you cannot move about
|
||||
in Time.”
|
||||
|
||||
“That is the germ of my great discovery. But you are wrong to say that
|
||||
we cannot move about in Time. For instance, if I am recalling an
|
||||
incident very vividly I go back to the instant of its occurrence: I
|
||||
become absent-minded, as you say. I jump back for a moment. Of course
|
||||
we have no means of staying back for any length of Time, any more than
|
||||
a savage or an animal has of staying six feet above the ground. But a
|
||||
civilised man is better off than the savage in this respect. He can go
|
||||
up against gravitation in a balloon, and why should he not hope that
|
||||
ultimately he may be able to stop or accelerate his drift along the
|
||||
Time-Dimension, or even turn about and travel the other way?”
|
||||
|
||||
“Oh, _this_,” began Filby, “is all—”
|
||||
|
||||
“Why not?” said the Time Traveller.
|
||||
|
||||
“It’s against reason,” said Filby.
|
||||
|
||||
“What reason?” said the Time Traveller.
|
||||
|
||||
“You can show black is white by argument,” said Filby, “but you will
|
||||
never convince me.”
|
||||
|
||||
“Possibly not,” said the Time Traveller. “But now you begin to see the
|
||||
object of my investigations into the geometry of Four Dimensions. Long
|
||||
ago I had a vague inkling of a machine—”
|
||||
|
||||
“To travel through Time!” exclaimed the Very Young Man.
|
||||
|
||||
“That shall travel indifferently in any direction of Space and Time, as
|
||||
the driver determines.”
|
||||
|
||||
Filby contented himself with laughter.
|
||||
|
||||
“But I have experimental verification,” said the Time Traveller.
|
||||
|
||||
“It would be remarkably convenient for the historian,” the Psychologist
|
||||
suggested. “One might travel back and verify the accepted account of
|
||||
the Battle of Hastings, for instance!”
|
||||
|
||||
“Don’t you think you would attract attention?” said the Medical Man.
|
||||
“Our ancestors had no great tolerance for anachronisms.”
|
||||
|
||||
“One might get one’s Greek from the very lips of Homer and Plato,” the
|
||||
Very Young Man thought.
|
||||
|
||||
“In which case they would certainly plough you for the Little-go. The
|
||||
German scholars have improved Greek so much.”
|
||||
|
||||
“Then there is the future,” said the Very Young Man. “Just think! One
|
||||
might invest all one’s money, leave it to accumulate at interest, and
|
||||
hurry on ahead!”
|
||||
|
||||
“To discover a society,” said I, “erected on a strictly communistic
|
||||
basis.”
|
||||
|
||||
“Of all the wild extravagant theories!” began the Psychologist.
|
||||
|
||||
“Yes, so it seemed to me, and so I never talked of it until—”
|
||||
|
||||
“Experimental verification!” cried I. “You are going to verify _that_?”
|
||||
|
||||
“The experiment!” cried Filby, who was getting brain-weary.
|
||||
|
||||
“Let’s see your experiment anyhow,” said the Psychologist, “though it’s
|
||||
all humbug, you know.”
|
||||
|
||||
The Time Traveller smiled round at us. Then, still smiling faintly, and
|
||||
with his hands deep in his trousers pockets, he walked slowly out of
|
||||
the room, and we heard his slippers shuffling down the long passage to
|
||||
his laboratory.
|
||||
|
||||
The Psychologist looked at us. “I wonder what he’s got?”
|
||||
|
||||
“Some sleight-of-hand trick or other,” said the Medical Man, and Filby
|
||||
tried to tell us about a conjuror he had seen at Burslem, but before he
|
||||
had finished his preface the Time Traveller came back, and Filby’s
|
||||
anecdote collapsed.
|
||||
@ -7,7 +7,7 @@ const siteMetadata = {
|
||||
language: 'zh-CN',
|
||||
theme: 'system', // system, dark or light
|
||||
siteUrl: 'https://ivanli.cc/',
|
||||
siteRepo: 'https://git.ivanli.cc/ivan/taliwind-nextjs-blog',
|
||||
siteRepo: 'https://git.ivanli.cc/ivan/tailwind-nextjs-blog',
|
||||
siteLogo:
|
||||
'https://pan.ivanli.cc/api/v3/file/source/1234/%E5%A4%B4%E5%83%8F.png?sign=xIgy54DyFRYupxjZJbK02HmpKX8C53YR-O0I18Rxm70%3D%3A0',
|
||||
image:
|
||||
|
||||
@ -8,7 +8,7 @@ import siteMetadata from '@/data/siteMetadata'
|
||||
import Comments from '@/components/comments'
|
||||
import ScrollTopAndComment from '@/components/ScrollTopAndComment'
|
||||
|
||||
const editUrl = (fileName) => `${siteMetadata.siteRepo}/blob/master/data/blog/${fileName}`
|
||||
const editUrl = (fileName) => `${siteMetadata.siteRepo}/raw/master/data/blog/${fileName}`
|
||||
const discussUrl = (slug) =>
|
||||
`https://mobile.twitter.com/search?q=${encodeURIComponent(
|
||||
`${siteMetadata.siteUrl}/blog/${slug}`
|
||||
@ -92,7 +92,7 @@ export default function PostLayout({ frontMatter, authorDetails, next, prev, chi
|
||||
{'Discuss on Twitter'}
|
||||
</Link>
|
||||
{` • `}
|
||||
<Link href={editUrl(fileName)}>{'View on GitHub'}</Link>
|
||||
<Link href={editUrl(fileName)}>{'View source'}</Link>
|
||||
</div>
|
||||
<Comments frontMatter={frontMatter} />
|
||||
</div>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user