使用 Wiki 还是 GitHub Pages

[TieBaMma]

WIKI的主要优点是能用MarkDown写，比直接改HTML还是要方便不少的……

另外，我姑且已经把WIKI的编辑权限给打开了……

[StephDC]

其實要不然把 MarkDown 扔進來 repo 然後每次更新 Wiki 時順便把 GitHub.io 這個 MarkDown 同步，然後使用 MarkDown 轉 HTML 程式 弄回 html 版？
最後一步弄回 html 這個可以弄個小 bash 腳本輕鬆搞定倒是

[Lemmingh]

@TieBaMma

在 2019 年这个时间点上看，我赞同 StephDC 的观点。显然，Markdown 易于编辑和检查，就像您说的那样。而且，编辑 Markdown 可以把主要精力放在文字安排和文档结构上，进而改善文档的排版。

在我看来，当前最佳解决方案有 3 种：

1. 在 repo 中存储 Markdown 源文件，并且每次编辑后同步生成 HTML 文件，一起 commit。
2. 改用 Jekyll，在 repo 中存储网站源文件（包含 Jekyll 的配置文件和 Markdown），交由 GitHub Pages 自动生成网站。
3. 在 repo 中存储 Markdown 源文件，交由用户的浏览器自动生成内容主体。

我个人略倾向于方案 1。我认为，就本项目的特点来说，最终呈现单纯 HTML 网页是较合适的。不过，后文会看到，仍然有必要引入一点 JavaScript。

但是，我推荐方案 3。它非常有竞争力，因为 Marked 和 markdown-it 之类的库很快，延迟极小，而且，部署远远比方案 1 和 2 简单，空间消耗也明显很小。此外，现在应该没有人禁用 JavaScript，不必担心无法加载。

---

常见的 Markdown 编译器（按首字母排序）

• kramdown: 基于 Ruby
• Markdown All in One: VS Code 扩展
• markdown-it: 支持 Node.js 和 Web 浏览器
• Marked: 支持 Node.js 和 Web 浏览器
• MarkdownViewer++: Notepad++ 插件
• Python-Markdown: 基于 Python
• PHP Markdown: 基于 PHP

我个人使用 VS Code 配合 Markdown All in One 和 markdownlint 扩展来编辑 Markdown。

---

迁移前的准备工作

写个 README.md 来确定编辑规范。主要工作是约定

• repo 结构
• 编码
• 书写风格
• 网页样式

值得注意的是，需要在 README.md 中提醒编辑者：
磁力链接 (magnet) 应当以 HTML a tag 嵌入，或者以 code block 呈现，以防编译错误。

---

具体迁移流程（方案 3）

本方案会修改 index.html，新增 content.md。

1. 把内容主体迁移到 Markdown

把 index.html 的 <section class="main-content"> 中的内容迁移到 content.md。
但 <footer class="site-footer"> 应该保留在 index.html 中，移到 main-content 下方。

2. 处理 index.html

下文使用 Marked 实现。

首先在 head 中增加

<script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>

之前已经把 <section class="main-content"> 中的内容迁移了，于是，现在添加一段 JavaScript 生成其内容。

<section class="main-content">Loading... JavaScript is required.</section>

<script>
'use strict';

(function () {
  const mainContainer = document.querySelector('section.main-content');

  function onFetchError(reason) {
    mainContainer.textContent = 'Network errors occurred.\nResaon: ' + reason + '\nRetry...';
    buildContent();
  }

  function buildContent() {
    fetch('/content.md').then(res => {
      if (res.ok)
      {
        res.text().then(markdownText => mainContainer.innerHTML = marked(markdownText));
      } else
      {
        onFetchError(res.status);
      }
    }, onFetchError);
  }

  buildContent();
})();
</script>

注意

• 此处假定本项目的编辑者都没有恶意行为。如果担心安全问题，就再用 DOMPurify 处理 Marked 的输出。
• 如果考虑上古（ES6 以前）兼容性，请把 JavaScript 代码中的 let 和 const 都改为 var，fetch 改用 XMLHttpRequest。
• jsDelivr 与 Cloudflare 等合作，提供中国大陆的 CDN 支持，加载通常很快。
• 不一定在 head 中加载 marked.min.js，出于美观考虑，可以把它紧贴在 <section class="main-content"> 之前。

测试

使用 Python SimpleHTTPServer (python -m http.server 80 --bind localhost) 搭建测试服务器；
网络不节流；
加载一个与本项目相等的网站；
使用 Firefox 68.0.2 (64 位) 的 开发者工具 分析性能。

结果如下

本方案与 https://tiebamma.github.io/InstallTutorial/ 相比，

没有缓存：
文件大小、传输量、传输耗时、响应时间均无明显差异。（传输量差异在 几十KB，传输耗时差异在 几百ms）。
增量主要来自 JS（加载 marked.min.js）和 XHR（加载 content.md），而本方案中 HTML 明显缩减又对总量有益。

初次缓存：
文件大小、传输量、传输耗时、响应时间均无明显差异。（传输量差异在 几十KB，传输耗时差异在 几十ms）。
看上去，再次访问网站时，所有文件都从浏览器缓存读取。

---

具体迁移流程（方案 1）

本方案会修改 index.html，新增 content.md 和 content.html。

1. 在 README.md 中强制实施一套操作流程

例如，若使用 VS Code，只要写好 .vscode/settings.json 配置文件，强制风格和生成网页就是自动的，后续的编辑者只需把精力放在 Markdown 上。

2. 把源文件迁移到 Markdown

这里，我推荐的方案是：将内容主体分离出来，建立文件 content.md；在 index.html 中使用 <iframe> 呈现 content.html。基于本文中所述的原因，仍需要在 Markdown 中内联少量 HTML，但应该不会影响编辑体验。

另外一种方案是，建立文件 index.md。把 <section class="page-header"> 等部分内联在 index.md 中。
但我不非常建议那种方案，因为它会大量破坏 Markdown 的易用性，导致跟直接编辑 HTML 没有区别。

先处理 index.html。把 <section class="main-content"> 中的内容迁移到 content.md 中，原位置替换为

<iframe src="content.html" referrerpolicy="no-referrer" style="border: none; display: block; position: fixed; left: 0; top: 10vh; height: 90vh; width: 100vw; z-index: -1;">main-content</iframe>

注意

这个 iframe 内联了以下样式

{
border: none;
display: block;
position: fixed;
left: 0;
top: 10vh;
height: 90vh;
width: 100vw;
z-index: -1;
}

与之配合，对 <section class="page-header"> 做如下修改：

首先，追加样式以调整 index.html

/**
  * The `.page-header` occupies the top 10% of the viewport.
  * The `.main-content > iframe` occupies the bottom 90% of the viewport.
  */

/* The combination of `max-height` and `min-height` allows the animations to be calculated correctly. */
.page-header {
  transition: all 0.3s ease-in;
  overflow: hidden;
  display: flex;
  max-height: 10vh;
  min-height: 10vh;
  align-items: baseline;
  justify-content: space-around;
  flex-wrap: wrap;
  animation: shrink_page_header 2s ease-in 0s;
}

.page-header:not(:hover) {
  padding-bottom: 0;
  padding-top: 0;
}

/* Provide an acceptable experience, especially on mobile. */
.page-header:hover,
.page-header:active,
.page-header:focus-within {
  overflow: auto;
  display: block; /* Activates styles in `stylesheet.css`. */
  max-height: 50vh;
}

/* To show the user the logic of the header. */
@keyframes shrink_page_header {
  from { max-height: 100vh; }
  to { max-height: 10vh; }
}

接着，删除无用元素，以避免 section.page-header 在 flex 时排版异常

<h2 class="project-tagline"></h2>

最后，我注意到，可能误触 .page-header 中的 a.btn。该误触是一个可能性非常小的情况，需要在狭小的触控屏上操作才出现，而且即使发生也对用户体验没有很大影响。
解决方案是，JavaScript 侦听事件，在焦点离开 .page-header 时，自动滚动它至其顶部。鉴于您在贴吧中指出，人们都使用电脑访问本项目，我暂不处理。

此外，content.md 中需要使用 <script> 引入我后文 超链接问题 中将要提到的 JS。中间正常地书写。
还要基于 stylesheet.css 为 content.html 设置样式。

那些不重要的细节，现在暂不讨论。

这里还有一个问题：
文档末尾的 <footer class="site-footer"> 页脚应该放在哪里？

• 应该内联到 content.md 的末尾呢
• 还是塞进 index.html 的 .page-header 中呢

---

超链接问题

本项目存在一些棘手的问题，比如超链接。目前，所有的链接默认都在当前页面的 context 中打开，有点影响阅读体验。尤其是方案 1，由于引入了 iframe，这会导致更加反直觉的现象。

顺便一提，.page-header 中的那两个 Download btn 的链接可能需要修正：
把 master 换成 gh-pages。

考虑到 a tag 数量众多。当前最佳解决方案是使用 JavaScript 批量修改 DOM，以强制所有的指向外部的超链接都在新窗口中打开。只需添加以下

'use strict';

// To force links to be opened in a new context.
// Only process links other than URL fragments. (A URL fragment points to an internal target location within the current document.)
// Some odd links might be processed accidently as well. However, we don't have to worry because those are usually deprecated usages.
// ! Caution: `aLink.href` returns full URI. Do NOT use it.
window.onload = function () {
  const aTags = document.getElementsByTagName('a');
  for (const aLink of aTags)
  {
    if (aLink.getAttribute('href') && aLink.getAttribute('href').match(/^[^#].*/))
    {
      aLink.target = "_blank";
      aLink.rel = "noreferrer noopener";
    }
  }
}

考虑到复用，假定把上述 JavaScript 代码写在一个名为 all.js 的文件中，那么只需在每个 HTML 文档中添加

<script src="all.js"></script>

另外，偷个懒，我还想在 all.js 中加一段

// Sets the base language to Chinese (Simplified). Using JS, we dont't have to check each HTML document every time.
document.documentElement.lang = 'zh-Hans';

---

对本项目内容的讨论

1. 处置失效和重定向的链接

据我观察，本项目中存在许多疑似失效的链接，似乎都是百度造成的问题，比如

• http://tieba.baidu.com/p/2570976088
• http://tieba.baidu.com/p/4024190694
• http://tieba.baidu.com/p/4172398243
• http://tieba.baidu.com/p/3204136180
• http://pan.baidu.com/share/link?shareid=188221&uk=1661347987

请问，如何处置它们？您是否有打算迁移这些内容？（毕竟百度贴吧隐藏帖子的行为可能会长期存在）

此外，有道云笔记似乎又更改了它们的 URL 格式，也许有必要更新文档中相关的分享链接。

2. 有关版本选择的提示语

2016-11-07，您在 Issue 7 中提到

对于版本8旁边那句“推荐使用这个版本”我一直在犹豫是不是该去掉

现在来看，那句话可以与其他几句话整合为一段。放在整个 下载地址 部分的开头，大致呈现如下

注意

英文版也可以调出中文提示，但是它没有中文帮助。只有带了中文帮助的才叫中文版！

---

Linux 版无中文版，自行汉化的方法可参考这帖。

---

Windows 版对 HDPI 显示器的支持不佳，导致显示模糊。该问题可能会长期存在。可以通过设置 高 DPI 缩放替代 为 应用程序，以及调节 Wolfram 笔记本的缩放等措施来暂缓。

---

没有太多需求的初学者可以考虑先上手版本 8，参考这帖。仍请注意兼容性等问题。

---

如无特殊原因请不要选择过老的版本！

1. 较老的 Mathematica 与现代的有许多不兼容之处。
2. 较老的 Mathematica 往往与现代的计算机不兼容，尤其是 Mac。
3. 在版本 7 以前，Mathematica 无官方中文版。
4. 早期 MMA 的自带文档非常简略。
5. 绘图和动画等功能在版本 6 时有过重大修改。

至于剩下的几条与特定版本强绑定的提示，保留在原处。
您看如何？

---

如果您同意的话，我可以实施上述迁移流程，并在大约 2 个月后提交一个 PR。

[TieBaMma]

@Lemmingh 这个……如果我没理解错的话，如果使用此方案的话，还需要编辑参与者自己装一个Markdown的编辑器？如果是这样的话，那这个方案可能并不比现有的直接改HTML的方法简单，而从近几年的实践来看，降低教程修改的门槛恐怕是目前的第一要务。（近几年在修正这篇教程的解说部分的人几乎只有我——当然，这也可能只是因为贴吧人气下降了，所以参与编辑的人少了。）（说实话，此刻我深刻地在担心，按你建议的方法改完之后会不会连我都不知道这教程要怎么编辑了……）

然后，关于教程内容——

百度隐藏17年1月以前帖子的问题目前基本无解，我曾试过使用网页时光机之类的网站对旧网页进行找回但未成功。（百度贴吧有反爬虫机制？）现在只能冀望于贴吧自己恢复。（实际上已经有一些帖子极缓慢地在恢复了。）我姑且在教程的开头加了段说明。

目前唯一过期的百度盘链接应该是版本8新注册机链接？那一整段可以考虑直接删掉。

试了一下，有道云笔记的链接似乎都还能用？那姑且不管。

教程这几年东一笔西一笔地改得是有些乱，是应该适当整理，不过，有些内容其实是我故意冗余的，比如中文版的问题，还有命令行注册机的问题。只在开头写一段是更有条理，但是有些人就是看不见。

[Lemmingh]

@TieBaMma

看来我写得太冗长了。🤦‍

---

方案 3 和 2 对编辑工具没有要求，教程编辑者甚至可以直接使用 GitHub 中内置的文本编辑器工作；但仍然推荐使用功能丰富且正确支持 CommonMark 的编辑器以减少编辑错误。

方案 1 必须在本地搭建完整的编译工具链。

---

这 3 种方案都需要重写网站文件。
在迁移完成后，

• 方案 3 和 2：教程编辑者只需编辑一个 Markdown 文件
• 方案 1：我写的那啰啰嗦嗦的一大堆

方案 3 的迁移工作尤其简单，就是把原先的内容搬走，改成几段代码，而且最后 repo 里也就新增几个文件（2 个 Markdown 是必需的，其余都是可选），一目了然。

所以我说

推荐方案 3。它非常有竞争力

---

百度的问题，看来只能静静等候了。

我查看了百度贴吧的 robots.txt。看上去，没有屏蔽对帖子的抓取（/p 路径），读取网页内容也不需要 JavaScript，搜索引擎检索 site:tieba.baidu.com 也有返回。
那么，如果你说的网络时光机是 archive.org 的话，我记得这个网站不会持续爬取所有网站的所有页面，好像是，那些没有被人特意标记的页面是按照热度爬取一部分。

---

说到爬虫，我想起来，按 方案 3 迁移后，编辑教程会变得轻松，不过，需要考虑一下怎样 SEO。我不太清楚搜索引擎对 .md 文件是否感兴趣。😅

---

关于提示语，那么，我现在的意见是

在 下载地址 部分的开头放一个完整的告示；
之后，确定需要重复的内容，贴到每一个子部分下。

[TieBaMma]

@Lemmingh 是的，我说的网页时光机是archive.org。看来Mathematica吧还是太冷了……（可是为什么连门可罗雀的果壳Mathematica小组的文章都能在archive.org找到而Mathematica吧却不能啊，贴吧怎么说也比果壳小组强吧……）

那就按方案3来改吧。具体有什么需要我做的吗？

关于提示语，那么，我现在的意见是

在 下载地址 部分的开头放一个完整的告示；
之后，确定需要重复的内容，贴到每一个子部分下。

同意。

[HyperGroups]

2019年啦，Jekyll太古老了，推荐一下yuque
@TieBaMma
https://www.yuque.com/mathematica

[Lemmingh]

@TieBaMma

非常感谢您的信任。

---

目前，需要您决定的有
（如果您没有明确某一部分，我将猜测其内容）

• 编码

  猜测：

  • UTF-8 (without BOM)
  • LF line ending
  • 文档末尾有换行符
  • HTML, CSS, JavaScript 的缩进为 2 个空格
  • Markdown 的缩进为 4 个空格

• <h2> 到 <h4> 的样式

  猜测：

  在现有基础上增加以下内容

  h2 {
    text-align: center;
    font-weight: bold;
  }
  
  h2, h3, h4, h5, h6 {
    border-top: 1px solid #eaecef;
    padding-top: .3em;
  }

• 下载地址部分开头的提示语，以及需要不断重复的提示语

• 目录结构以及是否需要 TOC

• Markdown 书写

  猜测：

  • 支持 CommonMark 0.29 语法
  • 使用 GitHub 推荐的书写风格

我打算在十一假期处理这件事。在此之前，您随时可以提出设计意见。

---

在开始之前，我还会考察 Ajax 的 SEO，以及怎样支持 IE。

• 按 方案 3 迁移后，网页内容通过 Ajax 加载，如果希望搜索引擎正常爬取内容，需要在 SEO 上花些功夫。
• Internet Explorer 对现代前端技术的支持非常差，它的最后一个版本 IE 11 发布于 2013 年，仍是一个老古董；它对 Ajax 的支持仅限于部分 XMLHttpRequest。然而，我注意到，现在还有人在使用 IE 访问这个教程，于是我只得考虑兼容。😰

如果实在太难处理，我可能会考虑添加几个配置文件，转成 方案 2。

---

非常抱歉，我这段时间比较忙，没能及时回复。

[TieBaMma]

@Lemmingh 啊~没事没事。而且我回的也不快啊。

编码和<h2>到<h4>的样式请随意，因为这个当初就是套的现成模板，从来没有认真考虑过。

开头的提示语用你之前拟定的就可以，需要不断重复的有：

注意，英文版也是可以调出中文提示的，但是它没有中文帮助，只有带了中文帮助的才叫中文版！

Linux版无中文版，自行汉化的方法可参……

……TOC是啥？Table Of Content？如果能有一个当然是最好。其实这个教程当年挂在wikia（现在好像改叫fandom了？）上的时候是有这个的，但是搬到github之后没人会弄……（顺便之所以会从wikia迁出来是因为wikia把这教程封了……）

MarkDown的具体版本我也不懂啊……可以支持基本的加粗，斜体，标题，分隔线，按键（<kbd>），划掉（<strike>），引用，代码，超链接，图片插入就行了吧。