Skip to content

Commit

Permalink
Update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
stevenjoezhang committed Dec 26, 2024
1 parent 859346b commit e1ab20d
Show file tree
Hide file tree
Showing 5 changed files with 25 additions and 18 deletions.
6 changes: 6 additions & 0 deletions source/docs/getting-started/deployment.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,12 @@ title: Deployment
description: NexT User Docs – Starting to Use β€” Deployment
---

There are two main methods for deploying a Hexo site:

1. **Local Deployment**: This traditional method involves generating site files locally by executing Hexo commands, and deploying the website to a server using rsync or git through the appropriate Hexo deployer plugin. This approach requires you to manually handle the deployment process each time you update your site.

2. **Continuous Integration (CI)**: This is a more efficient and automated deployment method. You simply upload your blog's source code to a git repository, and the site is generated and published through an automated process. This method leverages services like GitHub Actions, GitLab CI/CD, or other CI tools to automate the deployment, making updates and management easier and more consistent.

### Local Deployment

1. Modify files locally.
Expand Down
16 changes: 13 additions & 3 deletions source/docs/getting-started/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,17 @@ description: NexT User Docs – Starting to Use

### Hexo Installation

If this is your first time using Hexo, you can take some time to review the Hexo Docs to see [how to install Hexo](https://hexo.io/docs/) and [initialize a site](https://hexo.io/docs/setup). After the installation is successful, you should be able to execute `hexo` (or `npx hexo`) on the command line, and there must be `package.json`, `source`, `themes` and other directories in your {% label info@site root directory %}:
If this is your first time using Hexo, make sure you have the environment set up correctly. To get started, you need to:

1. **Install Node.js**: You can download the installer from the [Node.js official website](https://nodejs.org/), use the package management tool included with your operating system, or use a Node.js version management tool like [nvm](https://github.com/nvm-sh/nvm). After installation, you should be able to execute `node` and `npm` commands in the command line.

2. **Install Hexo CLI globally**: Run `npm i -g hexo-cli`. After this, you should be able to execute the `hexo` command in the command line.

3. **Initialize a Hexo site**: Execute `hexo init hexo-site`. You can replace `hexo-site` with another path name, but this document will use `hexo-site` as an example. This directory will be referred to as the {% label info@site root directory %} in the following text.

Ensure you have a reliable internet connection during the installation process. If you encounter any issues, consider configuring a proxy for npm or git, or using mirror sites.

For more detailed installation steps, please refer to the Hexo Docs to see [how to install Hexo](https://hexo.io/docs/) and [initialize a site](https://hexo.io/docs/setup). After the installation is successful, you should be able to execute `hexo` (or `npx hexo`) on the command line, and there must be `package.json`, `source`, `themes` and other directories in your {% label info@site root directory %}:

```bash
$ cd hexo-site
Expand Down Expand Up @@ -67,7 +77,7 @@ You can also read [detailed installation instructions](/docs/getting-started/ins

#### Upgrading NexT

A new version of NexT will be released every month. Please read the [release notes](https://github.com/next-theme/hexo-theme-next/releases) before updating the theme. You can update NexT by the following command.
The NexT theme will continue to release new versions to include new features and bug fixes. Please read the [release notes](https://github.com/next-theme/hexo-theme-next/releases) before updating the theme. You can update NexT by the following command.

{% tabs upgrading-next %}
<!-- tab Using <code>npm</code> -->
Expand Down Expand Up @@ -115,7 +125,7 @@ cp themes/next/_config.yml _config.next.yml
```

{% note warning %}
Please be aware that some other documents or tutorials may suggest creating or directly modifying files such as `themes/next/_config.yml` and `node_modules/hexo-theme-next/_config.yml`. Indeed, doing so can be accepted by Hexo and serve as your theme configuration file. However, this approach can lead to many inconveniences. It is quite often running into conflict status when updating NexT theme via `git pull`, or need to merge configurations manually when upgrading to new releases. For the theme installed through npm, it is also difficult to modify the {% label primary@NexT config file %} in `node_modules`. Therefore, please use the previously introduced `_config.next.yml` file as the theme's configuration file, and avoid creating or modifying other theme configuration files to prevent conflicts.
Please be aware that some other documents or tutorials may suggest creating or directly modifying files such as `themes/next/_config.yml` and `node_modules/hexo-theme-next/_config.yml`. Indeed, doing so can be accepted by Hexo and serve as your theme configuration file. However, this approach can lead to many inconveniences. For example, when upgrading the theme, custom modifications made to these default configuration files may lead to conflicts or be overwritten, causing data loss. Therefore, please use the previously introduced `_config.next.yml` file as the theme's configuration file, and avoid creating or modifying other theme configuration files to prevent conflicts.

For more information, please refer to [Alternate Theme Config](/docs/getting-started/configuration.html) feature documentation.
{% endnote %}
Expand Down
2 changes: 1 addition & 1 deletion source/docs/getting-started/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ description: NexT User Docs – Starting to Use – Detailed Installation

### Select Version

A new version of NexT will be released every month. You can choose to install the latest version or choose a stable old version.
The NexT theme will continue to release new versions to include new features and bug fixes. You can choose to install the latest version or choose a stable old version.

{% tabs download-next %}
<!-- tab {% label success@Latest Master Branch %} -->
Expand Down
17 changes: 4 additions & 13 deletions source/docs/getting-started/upgrade.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,18 +3,7 @@ title: Upgrade
description: NexT User Docs – Starting to Use – Upgrade
---

### NexT Compatibility with Hexo Version

| Version | Hexo 3.0.0-beta.4 or earlier | Hexo 3.0.0-rc.1 ~ 3.9 | Hexo 4.0 ~ 4.2.1 | Hexo 5.0 or later |
| ------------------------ | ----------------------------- | --------------------- | -------------------- | --------------------- |
| NexT v0.4.5.1 or earlier | βœ… | βœ… | ❌ Icon (2) | ❌ Icon (2) |
| NexT v0.4.5.2 ~ v7.4.1 | ⚠️ Data Files (1) | βœ… | ❌ Icon (2) | ❌ Icon (2) |
| NexT v7.4.2 ~ v8.1.0 | ⚠️ Data Files (1) | βœ… | βœ… | βœ… |
| NexT v8.2.0 or later | ⚠️ Nunjucks (3) | ⚠️ Nunjucks (3) | ⚠️ Nunjucks (3) | βœ… |

(1): Hexo 3.0.0-beta.4 or earlier does not support Data Files.
(2): Icons may not be displayed normally.
(3): Nunjucks renderer plugin required.
We always recommend users to use the latest versions of Node.js, Hexo, and NexT, as new versions of the software include new features and security patches. Some tutorials might use older versions of Hexo and NexT as examples, and their usage methods can serve as a reference, but it is not recommended to actually install these versions.

### NexT Repositories

Expand All @@ -24,7 +13,9 @@ Due to historical reasons, NexT has three different repositories.
| ----------- | ------- | --------------------------------------------- |
| 2014 ~ 2017 | v5 | https://github.com/iissnan/hexo-theme-next |
| 2018 ~ 2019 | v6 ~ v7 | https://github.com/theme-next/hexo-theme-next |
| 2020 | v8 | https://github.com/next-theme/hexo-theme-next |
| Since 2020 | v8 | https://github.com/next-theme/hexo-theme-next |

After 2020, the first two repositories have ceased updates. The currently active version is v8. Please ensure that you have installed the correct version.

### Upgrade from Legacy Version

Expand Down
2 changes: 1 addition & 1 deletion source/docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ We designed the NexT theme to support a wide range of mainstream browsers, inclu

*The criterion being that on these browsers, the core functionalities and styles of the NexT theme work normally, excluding third-party plugins.*

Many modern browsers, such as Chrome and Edge, support automatic updates, and we recommend users keep their browsers up to date. However, the versions of some browsers are tied to the operating system, such as Safari and IE, and NexT cannot guarantee compatibility with their older versions.
If you need to support older browsers that are not on the supported list, you might consider using tools like [Babel.js](https://babeljs.io).

### Customize Your NexT

Expand Down

0 comments on commit e1ab20d

Please sign in to comment.