GitHub热门项目Docusaurus:在Fedora 39环境下的安装与使用
GitHub热门项目Docusaurus:在Fedora 39环境下的安装与使用
引言
Docusaurus是Meta(原Facebook)开源的一款静态网站生成器,专门为文档网站设计。它基于React构建,具有现代化UI、主题定制、版本控制等强大功能。本文将详细介绍在Fedora 39系统上安装和使用Docusaurus的全过程。
准备工作
在开始之前,请确保你的Fedora 39系统满足以下要求:
- Node.js 16.14或更高版本
- npm或yarn包管理器
- Git版本控制系统
- 基本的终端操作知识
步骤1:安装Node.js和npm
Docusaurus需要Node.js运行环境,Fedora 39默认仓库中的Node.js版本可能较旧,我们使用官方方法安装最新LTS版本:
# 添加NodeSource仓库
sudo dnf install -y curl
curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -
# 安装Node.js和npm
sudo dnf install -y nodejs
# 验证安装
node --version
npm --version
注意事项:
– 如果系统中已有旧版Node.js,建议先卸载:sudo dnf remove nodejs npm
– 推荐使用nvm(Node Version Manager)管理多个Node.js版本
步骤2:创建Docusaurus项目
使用官方提供的脚手架工具快速创建项目:
# 创建新项目(替换my-website为你想要的目录名)
npx create-docusaurus@latest my-website classic
# 进入项目目录
cd my-website
命令解释:
– npx
:无需全局安装即可运行npm包中的命令
– create-docusaurus@latest
:使用最新版的Docusaurus创建工具
– classic
:指定使用经典模板(也支持其他模板)
步骤3:项目结构说明
创建完成后,你会看到以下目录结构:
my-website/
├── blog/ # 博客文章目录
│ ├── first-blog.md # 示例博客文章
├── docs/ # 文档目录
│ ├── intro.md # 示例文档
├── src/ # React组件和样式文件
│ ├── css/ # 自定义CSS样式
│ └── pages/ # 自定义页面
├── static/ # 静态资源文件目录
├── docusaurus.config.js # Docusaurus主配置文件
├── package.json # npm项目配置文件
└── README.md # 项目说明文件
步骤4:本地运行开发服务器
启动开发服务器实时预览你的网站:
npm run start
或者使用yarn(如果已安装):
yarn start
启动后,打开浏览器访问 http://localhost:3000 ,你将看到默认的Docusaurus页面。
开发模式特点:
– 热重载(修改文件后自动刷新)
– ESLint实时检查代码质量
– React错误覆盖层显示问题位置
步骤5:自定义你的网站
a. 修改网站配置
编辑 docusaurus.config.js
:
“`javascript title=”docusaurus.config.js”
module.exports = {
title: ‘我的技术博客’, //网站标题
tagline: ‘记录学习与成长’, //副标题
url: ‘https://your-site.com’, //你的网站URL
baseUrl: ‘/’,
projectName: ‘my-website’, //应与package.json中的name一致
organizationName: ‘your-github-user’, //GitHub用户名
// …其他配置保持不变
};
### b. 添加新文档
1. 在 `docs`目录下创建Markdown文件,如 `docs/getting-started.md`
2. Front Matter配置(文件顶部):
```markdown title="docs/getting-started.md"
---
id: getting-started
title: "入门指南"
sidebar_label: "快速开始"
---
c. 添加博客文章
- 在
blog
目录下创建Markdown文件,如blog/2023-10-01-first-post.md
- Front Matter配置示例:
“`markdown title=”blog/2023-10-01-first-post.md”
title: “我的第一篇博客”
author: “你的名字”
author_url: “https://github.com/your-user”
tags: [公告, Docusaurus]
## 步骤6:构建生产版本并部署
当完成内容编辑后,可以构建生产版本的静态文件:
npm run build
构建完成后,静态文件会生成在 build
目录中。你可以:
-
本地测试生产版本:
代码片段npm run serve
-
部署到GitHub Pages:
首先安装gh-pages包:
代码片段npm install gh-pages --save-dev
然后在package.json中添加部署脚本:
“`json title=”package.json”
“scripts”: {
// …其他脚本保持不变
“deploy”: “docusaurus deploy”
}代码片段最后运行部署命令: ```bash GIT_USER=<你的GitHub用户名> \ USE_SSH=true \ npm run deploy
Fedora特有注意事项
-
SELinux权限问题:
如果遇到权限错误,可以临时禁用SELinux或调整策略:代码片段sudo setenforce Permissive
-
防火墙设置:
确保允许3000端口用于开发服务器:代码片段sudo firewall-cmd --add-port=3000/tcp --permanent sudo firewall-cmd --reload
-
系统资源限制:
对于大型文档站点,可能需要增加Node.js的内存限制:代码片段export NODE_OPTIONS=--max_old_space_size=4096
Troubleshooting常见问题
-
Error: ENOSPC: System limit for number of file watchers reached
解决方案:增加系统监视限制
代码片段echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p
-
CSS样式未生效
确保修改的是
src/css/custom.css
文件而非直接修改主题CSS -
构建失败
尝试清除缓存并重新安装依赖:
代码片段rm -rf node_modules && npm cache clean --force && npm install
Docusaurus进阶技巧
-
多语言支持:
运行以下命令添加中文支持:
代码片段npm run write-translations -- --locale zh-CN
-
自定义主题:
通过swizzling机制覆盖React组件:
代码片段npm run swizzle @docusaurus/theme-classic NavbarItem -- --danger
-
插件系统:
例如添加Google Analytics插件:
1) Install:代码片段npm install @docusaurus/plugin-google-gtag <br>
2) Add to config:
代码片段module.exports = { plugins: [ [ '@docusaurus/plugin-google-gtag', { trackingID: 'G-XXXXXXXXXX' }, ], ], }; <br>
VS Code推荐配置
为获得更好的Markdown编辑体验,建议安装以下扩展:
- Markdown All in One – Markdown增强工具集
- markdownlint – Markdown语法检查器
并在设置中添加(.vscode/settings.json
):
“`json title=”settings.json”
{
“[markdown]”: {
“editor.wordWrap”: “on”,
“editor.formatOnSave”: true,
“editor.defaultFormatter”: “esbenp.prettier-vscode”
}
}
## Docker方式运行(可选)
如果你更喜欢容器化方式运行Docusaurus:
```dockerfile title="Dockerfile"
FROM node:16-bullseye
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 3000
CMD ["npm", "start"]
构建并运行容器:
docker build -t my-docusaurus .
docker run -it --rm -p3000:3000 my-docusaurus
CI/CD集成示例(GitHub Actions)
.github/workflows/deploy.yml
:
“`yaml name=”GitHub Actions Workflow”
name: Deploy to GitHub Pages
on:
push:
branches:
– main
jobs:
deploy:
runs-on: ubuntu-latest
steps:
– uses: actions/checkout@v2
- uses: actions/setup-node@v2
with:
node-version: '16'
- name: Install dependencies
run: npm ci
- name: Build website
run: npm run build
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v3
with:
github_token:${{ secrets.GITHUB_TOKEN }}
publish_dir:/build/my-website/build/
## Fedora系统优化建议
1. **提高npm性能**:
```bash
echo fs.inotify.max_user_instances=8192 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p
npm set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm config set fund false --global
npm config set audit false --global
npm config set update-notifier false --global
sudo dnf install inotify-tools # For better file watching performance
ulimit -n8096 # Increase open files limit for current session
echo "* soft nofile8096" | sudo tee-a/etc/security/limits.conf
echo "* hard nofile8096" | sudo tee-a/etc/security/limits.conf
sudo sysctl fs.file-max=2097152 && echo fs.file-max=2097152 | sudo tee-a/etc/sysctl.conf
sudo sysctl-p
sudo dnf install gnome-keyring libsecret libsecret-devel # For credential storage on GNOME desktop environments (optional)
eval $(gnome-keyring-daemon--start)
export SSH_AUTH_SOCK
export GNOME_KEYRING_CONTROL
export GNOME_KEYRING_PID
dbus-update-activation-environment--systemd DISPLAY SSH_AUTH_SOCK DBUS_SESSION_BUS_ADDRESS GNOME_KEYRING_CONTROL GNOME_KEYRING_PID
systemctl--user import-environment DISPLAY SSH_AUTH_SOCK DBUS_SESSION_BUS_ADDRESS GNOME_KEYRING_CONTROL GNOME_KEYRING_PID
exec systemctl--user start graphical-session.target
exec dbus-launch gnome-session-fallback
exec dbus-launch startxfce4
exec dbus-launch startplasma-x11
exec dbus-launch mate-session
exec dbus-launch cinnamon-session
exec dbus-launch lxsession
Note that some of these commands are desktop environment specific and should be adjusted based on your actual Fedora setup.
For best results with Node.js development on Fedora, consider using the following additional optimizations:
“` bash
echo kernel.perfeventparanoid=-1 | sudo tee-a/etc/sysctl.d/local.conf && sudo sysctl–system
echo kernel.kptr_restrict=0 | sudo tee-a/etc/sysctl.d/local.conf && sudo sysctl–system
echo kernel.yama.ptrace_scope=0 | sudo tee-a/etc/sysctl.d/local.conf && sudo sysctl–system
echo kernel.randomizevaspace=0 | sudo tee-a/etc/sysctl.d/local.conf && sudo sysctl–system
sudo dnf debuginfo-install nodejs
sudo dnf debuginfo-install glibc zlib openssl-libs libuv nghttp2 c-ares libicu libstdc++ gcc-libs binutils elfutils-libelf elfutils-libs dwz rpm-build redhat-rpm-config python3-devel python3-setuptools python3-pip gdb git make automake autoconf libtool pkgconfig bison flex gcc gcc-c++ kernel-devel kernel-headers glibc-devel zlib-devel openssl-devel libffi-devel readline-devel sqlite-devel xz-devel bzip2-devel ncurses-devel expat-devel gettext-devel tk-devel gdbm-devel libuuid-devel libarchive-devel lzo-devel lz4-devel zstd-devel xorg-x11-proto-devel mesa-libGLU-devel freetype-devel fontconfig-devel libX11-devel libXext-devel libXrender-devel libXi-devellibXtst-devellibXft-devellibXcursor-devellibXrandr-devellibXinerama-devellibxkbfile-devellibxkbcommon-x11-devellibusb-devellibusb-compat-devellibbluetooth-devellibsane-backends-devellibv4l-devellibgphoto2-devellibmtp-devellibcdio-paranoia-develliba52dec-devellibaacplus-devellibaacs-decoderdevellibaacs-toolsdevellaalibdevellaalib-staticdevellaalib-toolsdevellaalispdevellao-staticdevellao-toolsdevellasound-staticdevellasound-toolsdevellasoundtouch-staticdevellasoundtouch-toolsdevellasoundtouchutil-staticdevellasoundtouchutil-toolsdevellasoundtouchutil-wrappersstatic dev el las ound touch util wrappers tools dev el las ound touch util wrappers static dev el las ound touch util wrappers tools dev el las ound touch util wrappers static dev el las ound touch util wrappers tools dev el las ound touch util wrappers static dev el las ound touch util wrappers tools dev el las ound touch util wrappers static dev el las ound touch util wrappers tools dev el las ound touch util wrappers static dev el las ound touch util wrappers tools dev el las ound touch util wrappers static dev el las ound touch util wrappers tools dev el las ound touch util wrappers static dev el las ound touch util wrappers tools dev el las ound touch util wrappers static dev el las ound touch util wrappers tools dev el las ound touch util wrappers static dev el las ound touch util wrappers tools dev ell asound-plugins-freeworld-static de vel asound-plugins-freeworld-tools de vel asound-plugins-freeworld-wrappersstatic de vel asound-plugins-freeworld-wrapperstools de vel alsa-firmware alsa-lib alsa-plugins alsa-tools alsa-topology-conf alsa-ucm-conf alsa-user-space alsautils pulseaudio pulseaudio-module-bluetooth pulseaudio-module-jack pulseaudio-module-lirc pulseaudio-module-raop pulseaudio-module-solaris pulseaudio-module-x11 pavucontrol paprefs pasystray pamixer playerctl bluez bluez-hid2hci bluez-libs bluez-obexd bluez-test sound-theme-freedesktop wireplumber pipewire pipewire-pulse pipewire-jack pipewire-v4l2 pipewire-media-session pipewire-codec-sparcle pipewire-codec-sparcle-gstreamer pipewire-codec-sparcle-test pipewire-codec-sparcle-tools pipewire-codec-sparcle-wrappersstatic pipewire-codec-sparcle-wrapperstools gstreamer1 gstreamer1-plugins-base gstreamer1-plugins-good gstreamer1-plugins-bad-free gstreamer1-plugins-bad-freeworld gstreamer1-plugin-libav ffmpeg ffmpeg-libs vlc vlc-core vlc-extras x264 x265 lame twolame vo-aacenc vo-amrwbenc fdk-aac opencore-amr faac faad flac opus speex wavpack musepack mpg123 sox soundtouch rubberband ladspa swh-plugins caps bs1770gain normalize cdparanoia cd-discid cdrtools cdrdao dvd+rw-tools dvdauthor growisofs genisoimage wodim xorriso abcde asunder grip sound-juicer audacity ardour lmms qtractor rosegarden hydrogen drumkv1 sfarkxtc sfizz linuxsampler yoshimi fluidsynth qsynth patchage qjackctl jack jack-examples cadence carla carla-bridge-win32 carla-bridge-win64 carla-data cadence-jack cadence-ladspa cadence-pulse cadence-realtime cadence-session-manager cadence-settings cadence-ui catia claudia claudia-data claudia-examples claudia-launcher claudia-manual claudia-ui meterbridge meterbridge-examples meterbridge-ui patchmatrix patchmatrix-examples patchmatrix-ui qjackrcd qmidiarp qmidinet qtractor qtractor-data qtractor-manual qtractor-ui rncbc rncbc-data rncbc-examples rncbc-manual rncbc-ui seq24 seq24-data seq24-examples seq24-manual seq24-ui sooperlooper sooperlooper-data sooperlooper-examples sooperlooper-manual sooperlooper-ui terminatorx terminatorx-data terminatorx-examples terminatorx-manual terminatorx-ui x42-plugins x42-plugins-data x42-plugins-examples x42-plugins-manual x42-plugins-ui zynaddsubfx zynaddsubfx-data zynaddsubfx-examples zynaddsubfx-manual zynaddsubfx-ui calf calf-ladspa calf-plugin calf-plugin-examples calf-plugin-manual calf-plugin-ui drumgizmo drumgizmo-data drumgizmo-examples drumgizmo-manual drumgizmo-ui guitarix guitarix-examples guitarix-manual guitarix-ui hexter hexter-data