Wikidot进阶教程

如果你已经不再满足于朴实无华的一般页面和平淡乏味的普通文字呈现方式,希望基于站点提供的功能为你的文章或者页面添加更多实用或者花哨的效果——在大多数情况下,Wikidot能实现相当多复杂的功能。在Wikidot过去的二十年里,几个相当活跃的维基社区集结了许多有才华的Wikidot开发者,他们通过Wikidot提供的[[include]][[module]]功能,实现了相当多现代化的样式和功能。

如果你也希望了解如何自行研发或者搬运一些功能,你可以参考在这个页面中列出来的相当多文章。然而这些文章是由各国开发者分别撰写的,而且大多数侧重于功能的实现而不涉及原理的解析,使得复制粘贴的成本大大降低,但一定程度上提高了希望自行开发某些组件的用户进行参考学习的难度。

基于上述情况,笔者希望通过此篇Wikidot进阶教程,系统地总结前人成果中使用到的技术,并且介绍它们的开发方法以及一些Wikidot的不常用功能,希望能对你有所帮助。

值得注意的是,Wikidot的功能在超过十年前就停止了更新,Wikidot垂垂老矣,但是仍然能够为你提供相当多的可能性。只要你想。

现在让我们开始吧。


注意!

在阅读本文前,笔者默认你已经:

  • 阅读过Wikidot使用说明Wikidot语法,并且基本熟练Wikidot的使用方式。
  • 初步了解了部分前端知识,包括HTMLJavaScriptCSS,它们在一般网页中的作用和调用方式。
  • 至少了解了浏览器的运作方式,包括事件循环原理和渲染进程。

上述内容按照重要性降序排列,对于涉及上述内容的术语(即非Wikidot专用的网络技术),本文将不会单独阐述。

  • 如果你尚未满足第一项条件,你很难看懂这篇文章;
  • 如果你尚未满足第二项条件,你可能在某些环节有些困惑,建议你自行搜索相关术语;
  • 如果你只是不了解最后一项,你可以阅读本文的绝大多数内容。

Wikidot方法

这部分的内容是可以通过维基语法或者其他方式调用的Wikidot功能。且不包含在常用Wikidot语法之内。这部分的内容来自 Wikidot Documentation,并且结合实际使用情况作了补充。

概念:Wikidot标签和模组

Wikidot内置了许多操纵与构建HTML元素的方法,Wikidot语法实质是一种简化的标记语言。除了在常用Wikidot语法中介绍的行内格式意外事件,它们一般通过方块(Blocks)模组(Modules)两类标签来调用。
方块标签
常规的方块标签是以两对方括号[[]]括起的内容,方块的结构如下(以[[div]]方块为例):

开始标签:方块名(name)[[div 方块体(body)id="" style="" data-value="" …]]
结束标签:[[/div]]

也有非常规的方块标签(不以两对方括号[[]]括起)。
模组标签
模组标签可以看作是一类特殊的方块标签,共同特征是方块名均为[[module,方块体为Wikidot允许的特定字符串,如Listpages]]

注意

  • 方块名可能会以下划线(_)结尾,这表明这是一个非换行标签1
  • 大多数标签都允许通过方块体传入额外参数,请查阅下方表格以获取特定标签的参数范围;
  • 部分标签不需要同名的结束标签,请查阅下方表格获取特定标签的闭合性;

标签参照表

请在需要时参考。


这部分功能通常在一个标准Wikidot页面内使用。用法和功能比较单一。

概念:行内标签和块状标签

如果你了解什么是CSS盒模型以及行盒、块盒、行块盒,这部分则相当易于理解。

你可能已经见过了[[div]]方块和[[span]]元素。它们的区别在于,[[div]]及其结束标签[[/div]]都需要单独成行,否则无法成功创建一个[[div]]方块;而[[span]]及其结束标签[[/span]]则可以在一行内使用。这就是行盒与块盒的区别。

块状标签
在Wikidot中,有些标签(例如[[code]][[div]][[HTML]][[iframe]][[iftags]][[math]]等)具有类似的性质,他们都具有结束标签并且两个标签都需要独占一行,仿照HTML的术语,这些标签应当为块状标签。块状标签的性质有:
  • 标签成对出现,语法成对;
  • 标签需要独占一行,前后都不能有任何字符;
  • 可以嵌套;
  • 可以包含行内标签;
行内标签
而有些标签(例如[[a]][[span]]以及大多数Wikidot行内语法)则不要求两个标签都位于独立行中才能发挥作用,这些标签应当为行内标签。行内标签的性质有:
  • 标签成对出现,语法成对;
  • 标签不需要独占一行,前后都可以有字符
  • 部分行内标签可以嵌套;
  • 不能包含块状标签
特殊标签
HTML类似,有些标签是自闭合标签(或者空标签),没有结束符。例如:
  • [[image]]
  • 四个连用的@(@@@@,等效于<br>);
  • 四个及以上连用的“-”(-----,等效于<hr>)。

注意

  • 上述Wikidot的标签说明只是阐述调用方式,并不等效于浏览器文本流的生成方式以及渲染方式。例如,你可以规定一个[[span]]块具有display: block样式,这会覆盖掉默认的inline样式,此标签呈现为块级元素并截断文本流。
  • HTML类似,大部分开始标签可以直接声明参数,这在制作[[include]]组件时很有帮助。例如,你可以通过为[[div]]方块设定不同的<data-value>值以便在CSS中更好地利用属性选择器来分配不同样式。
  • 特别地,<style>参数同样会直接指定元素内联样式;<class>属性会指定站点或者页面应用的CSS文件中已经定义的类。

参考文献

参考文献的组件包括两个部分:参考文献方块[[bibliography]][[/bibliography]]}})与引用位点[((bibcite label))]),两个部分必需同时使用,否则你无法得到正确的参考文献格式。例如:

……在实际的生产环境和过程中,创作者往往还需要考虑作品阅读对象的问题。标题的目的性专门用以解释标题在实际用途中显示出来的某些特点。标题的目的性通常与作品的用途及领域强相关。例如,在学术领域中的论文文体,其标题通常采用复式结构,如《起伏不定的情感:生命历程视域下的粉丝持续性认同研究》[1]以及 《“理想批评家”与当代文学研究的新范式——以《路遥的哈姆雷特与莎士比亚》为考察对象》[2]。通常而言,这类题目具有如下特征:


参考文献
1. 晏青,宋宝儿.起伏不定的情感:生命历程视域下的粉丝持续性认同研究[J/OL].现代出版:1-20[2024-02-06].
2. 王鹏程.“理想批评家”与当代文学研究的新范式——以《路遥的哈姆雷特与莎士比亚》为考察对象[J].中国当代文学研究,2024(011):206-213.
……在实际的生产环境和过程中,创作者往往还需要考虑作品阅读对象的问题。标题的目的性专门用以解释标题在实际用途中显示出来的某些特点。标题的目的性通常与作品的用途及领域强相关。例如,在学术领域中的论文文体,其标题通常采用复式结构,如《起伏不定的情感:生命历程视域下的粉丝持续性认同研究》[((bibcite 1))]以及《“理想批评家”与当代文学研究的新范式——以《路遥的哈姆雷特与莎士比亚》为考察对象》[((bibcite 2))]。通常而言,这类题目具有如下特征:
----
[[bibliography title="参考文献"]]
: 1 : 晏青,宋宝儿.起伏不定的情感:生命历程视域下的粉丝持续性认同研究[J/OL].现代出版:1-20[2024-02-06].
: 2 : 王鹏程.“理想批评家”与当代文学研究的新范式——以《路遥的哈姆雷特与莎士比亚》为考察对象[J].中国当代文学研究,2024(011):206-213.
[[/bibliography]]

使用方式:

  • 在需要插入参考文献的地方插入[((bibcite label))],然后把label改成这个引用的名字(类似于锚点名称),不能使用汉字;
  • 插入数学表达式方块,在两个冒号中间填入已经创建的引用名称,两个冒号后面填入你的引用文献格式和doi等;
  • 大功告成!现在,脚注方块应该会按照你填入的标签名称显示出你创建的引用文献。
  • [[bibliography]]方块和脚注方块有些类似:在一个页面中只能有一个参考文献方块,可以接收title=""参数修改参考文献方块标题。
  • 你不应该在脚注方块中使用参考文献,尽管在一般网站上它们可以显示,但是在这个网站上不行。这不规范。

数学表达式

数学表达式有两种:块级数学表达式([[math]])和行内数学表达式([[$ LaTeX $]])。数学表达式必需与LaTeX13代码联用,否则你无法得到正确的数学表达式。例如:

(1)
\begin{align} e^{i\pi}+1=0 \end{align}

或者
$e^{i\pi}+1=0$

[[math]]
e^{i\pi}+1=0
[[/math]]
或者:
[[$ e^{i\pi}+1=0 $]]

这二者的区别是,使用块级数学表达式创建的式子允许你通过直接在开始标签后为某个数学表达式命名(如[[math xxx]]),从而能够使用公式引用向导识别到此式,在正文需要的位置引用它,例如:

Here, for a lattice $L \subset \mathbb{R}^{n}$ and $s>0$,

(2)
\begin{align} \rho_{s}(L):=\sum_{\boldsymbol{y} \in L} e^{-\pi\|\boldsymbol{y}\|^{2} / s^{2}} \end{align}

is the Gaussian mass of the lattice with parameter $s$. This can be seen as a smooth version of the point-counting function $r \mapsto\left|L \cap r B_{2}^{n}\right|$, with the parameter $s$ playing the role of the radius $r$, and it arises naturally in a number of contexts (often in the form of the theta function, $\Theta_{\mathcal{L}}(i y):=\rho_{1 / \sqrt{y}}(\mathcal{L})$ ). In particular, Theorem 1.2 immediately implies that $\left|L \cap r B_{2}^{n}\right| \leq 3 e^{\pi t^{2} r^{2}} / 2$ for any radius $r>0$. (We note that the constant $3 / 2$ in this bound and the theorem statement is chosen for convenience, and a similar statement holds with any constant strictly bigger than 1.)
….


参照表达式2(Eq.(2)),可知:

Here, for a lattice [[$L \subset \mathbb{R}^{n}$]] and [[$s>0$]],

[[math equation]]
\rho_{s}(L):=\sum_{\boldsymbol{y} \in L} e^{-\pi\|\boldsymbol{y}\|^{2} / s^{2}}
[[/math]]

is the Gaussian mass of the lattice with parameter [[$s$]]. This can be seen as a smooth version of the point-counting function [[$r \mapsto\left|L \cap r B_{2}^{n}\right|$]], with the parameter [[$s$]] playing the role of the radius [[$r$]], and it arises naturally in a number of contexts (often in the form of the theta function, [[$\Theta_{\mathcal{L}}(i y):=\rho_{1 / \sqrt{y}}(\mathcal{L})$]] ). In particular, Theorem 1.2 immediately implies that [[$\left|L \cap r B_{2}^{n}\right| \leq 3 e^{\pi t^{2} r^{2}} / 2$]] for any radius [[$r>0$]]. (We note that the constant [[$3 / 2$]] in this bound and the theorem statement is chosen for convenience, and a similar statement holds with any constant strictly bigger than 1.)
....
----
参照表达式[[eref equation]](Eq.([[eref equation]])),可知:

除非你的正文中已经有正确命名(不能使用汉字)的块级数学表达式,否则公式引用向导不会正常工作,你也可以使用[[eref xxx]]手动创建指向被标记为xxx的数学表达式。

实际上,与LaTeX语法相比,Wikidot语法只做了如下改动:

  • 在行内表达式中,用两对方括号包围了以$做标识符的LaTeX语句;
  • 在块级表达式中,用[[math]][[/math]]替代了$$作为开始和结束标签;

这在你进行LaTeX-Wikidot语法转换时可能有用。

按钮

联HTML文(iframe)

内联插件(embed)

可用模组

基础CSS操作方法

更好的编辑方式

必须承认的一点是,在进行繁重的代码编辑任务时,Wikidot的编辑器是十分匮乏的。没有同步修改,没有多视图编辑,没有高亮显示、括号检查和极其有限的自动补全,使得纯Wikidot的编辑方式效率受到了严重的限制。

在行业中,我们一般使用集成开发环境(IDE)15完成代码编辑和调试任务,并且使用版本控制系统16和代码托管平台17管理项目的多人协作以及分发需求。在基于Wikidot的开发场景中,Wikidot本身就具有一定程度的代码托管版本控制功能,理想的状态下,还应当有远程拉取/上传与类似Git的本地分支暂存与发布的功能。

移动端功能说明
插件的功能清单(v0.2.4
功能说明
插件的功能清单(v0.2.4


为了弥补Wikidot编辑器缺失的重要功能,我推荐你使用VScode进行代码编辑,并安装由JochoiJochoi(Zokhoi,或称鑿海)开发的VScode插件:FTML/Wikidot Workshop18

根据作者在插件主页的说明,此插件的功能有:

  • 语法高亮(对于具有下列扩展后缀名的文件生效:.ftml.wd.wikidot.wj.wikijump
  • Wikidot语法预览(使用内部窗口,无需连接Wikidot);

以下功能需要桌面版VScode:

  • 拉取Wikidot页面源代码与元信息19
  • 检视本地代码与远程代码差异;
  • 推送本地更改。

基础 [[include]]方法

基础 Wikidot表单(Form)

除非特别注明,本站内容采用 Creative Commons Attribution-NonCommercial-ShareAlike 4.0 协议授权。