NotionNext二次开发手册
NotionNext二次开发手册
category
技术工具
tags
NotionNext
type
Post
slug
how-to-develop-with-notion-next
summary
小白入门如何开发notionnext,下载NotionNext、启动NotionNext、提交合并到NotionNext等。
status
Published
date
Nov 13, 2022
icon
password
💡
此文已迁移:请移步 NotionNext文档中心→《二次开发手册》查看,此处只保留旧版本快照。

前言

在进行二次开发之前,您需要了解到:NotionNext本身支持大量的自定义配置,开发之前,请先访问《NotionNext操作手册》获取帮助、配置您的站点,例如:
  • blog.config.js 文件中可以修改站点的基础信息、主题、语言、评论插件等核心配置
  • 每个主题下都有一个配置文件config_[theme].js,以便用户配置自己的页面个性化。
    • NotionNext 代码结构
      NotionNext 代码结构

自定义脚本

NotionNext操作手册中,有关于自定义脚本和样式的引入方式;即:
  1. /public/js/custom.js /public/css/custom.css 中引入您的脚本,就可以实现任意的页面功能。
  1. blog.config.jsCUSTOM_EXTERNAL_JSCUSTOM_EXTERNAL_CSS中也可以引入第三方的脚本。
💡
用这两种方式引入脚本,即使本机上没有安装nodejs等开发环境,也可以直接在浏览器控制台中编写调试。

自行开发

如果上述的配置方式,不能满足您的需要,例如新增组件、深度定制等等。您可以选择在github上发起issue,提出改进页面的建议,或者遵循此教程,进行您的开发之旅。
💡
可选Codespaces云开发,以及本地开发两种方案。

一、云开发(Codespaces)

💡
这是一个可选方案,相比本地开发,您不需要在电脑上安装环境;直接将Github仓库导入到云开发环境,在线编辑即可。 Codespaces是Github官方提供的云开发环境。

导入启动项目

二、 本地开发

准备开发环境

导入启动项目

代码结构简介

NextJS

项目用NextJS框架构建,以下是代码所有主要目录,修改样式主要在themes 目录下完成。
notion image

TailWindCSS

项目开发使用TailwindCss,这是一个极简、灵活的CSS工具库,上手后开发效率极高。
TailwindCSS为什么你要使用?
TailwindCSS官方称一个可以让你脱离css文件,在html直接通过class修改样式的框架。 但是TailwindCSS一直受到CSS 方案备受争议。第一个问题就是这和写style css有什么区别? 首先在我们的进行修改css样式的风法中,多多少少会用到一些4中方式 越往下走,颗粒度越来越大,约束性变高,自由性不足。而 TailwindCSS 位于第二层。 第一层的话,就很难复用了,所以 TailwindCSS 选择了第二层的原因。 在不久之前Facebook经过重构后的css体积已经重原来的413kb 压缩到74kb。 可是很多开发者,很疑惑。我的css文件下去了,但是我的html和组件的文件变得无比的大,并不知道这里的好处在哪里? 首先第一,现在的开发模式已经是组件开发了,就算你在搞一个css来维护。其实很多的样式属性这个组件有,那个组件也存在复用。这个没有必要,这里的自己的组件样式交给组件自己维护就好了。 第二点就是想到这个疑惑的,估计是没有去了解过nginx的gzip。只是知道有这么一回事。 gzip 的核心Deflate使用的是LZ77 算法和 Huffman 编码来压缩文件,重复度越高的文件可压缩的空间就越大。 即使 HTML 因为类名过多造成体积增大,由于 class 高度相似,gzip 也将会得到一个很大的压缩比例。 这才是 TailwindCSS 想要的结果 第一次我使用 tailwind ui 框架的时候,很多情况看多以下的这种写法。 你想要多少的数值,直接写多少就好了。 还有对应响应式 对应你使用的@media,你感觉谁更加舒服呢? 第三 就是后期维护的时候,就算有人跑路了,这么多个css,后面的人只需要去看html就能维护。这么多的css file你慢慢找吧,反正我是不想找的。 第四 Jit css编译,使用TailwindCSS在编译的过程中,比css-loader less-loader 都要快 说了这么这些好处,TailwindCSS有什么不足呢?我说说我的看法吧。 第一遇到复杂一点的css操作你不能直接使用 TailwindCSS 操作 比如以上的情况,你需要写css来操作子元素的显示,除非你无聊非要用js来写,也不是不行。 第二是增加了记忆负担,它的命名和你认知中的使用不一样,前期需要一直查阅文档,或者下载TailwindCSS的提示插件。要不你无从下手。 但是一旦你有习惯了,形成条件反射,那就是另一种情况,你会直喊香。 如果你正在做代码加速优化的话,你可以试试TailwindCSS.因为gzip后是真的小。 如果你是一个爱折腾的人,可是试试TailwindCSS。 如果你感觉你的组件已经可以完全独立使用一个css的时候,可以使用TailwindCSS来制作这个组件。后面要改代码时候,只需要去这个组件修改,并且不用担心自己的class会影响到他人的组件。
TailwindCSS为什么你要使用?
 

提交/贡献代码

通过GithubDesktop等工具,将您的代码提交后,推送到Github云端即可,Vercel会自动部署代码中的更新。

1.创建新主题

如果您想创建一个新主题、并提交到NotionNext,请复制一个/themes/example文件夹在themes目录下,并修改文件夹的名称主题的名称。

2.添加本地化

如果您的语言尚未得到NotionNext的支持,欢迎贡献本地化!按照以下步骤添加新的本地化: 1. 在/lib/lang中复制一个en-US.js文件,并将文件命名为语言的代码(例如zh-CN.js)。 2. 开始翻译字符串。 3. 将您的语言配置添加到lang.js中。
 
欢迎将你的代码分支,合并到NotionNext主仓库中,要为NotionNext做出贡献,请按照以下步骤操作:

3.提交代码到NotionNext

  1. 将存储库fork到您的GitHub帐户。
  1. 将存储库clone到您的设备上(或使用Codespaces之类的东西)。
  1. 在存储库中创建一个新分支,分支名按照改动的内容命名,建议是feat/bug/开头。
  1. 在分支中进行修改。
  1. 提交修改并推送分支。(请勿在分支中提交您自己的配置信息)
  1. 从fork中的分支创建到NotionNext的main分支的PR
  • NotionNext
  • 人和人的差别从来不是“天赋”,而是刻意练习的能力NotionNext如何使用公告功能