search

TieBaMma / InstallTutorial

https://tiebamma.github.io/InstallTutorial/
Creative Commons Attribution 4.0 International
677 stars 92 forks source link

使用 Wiki 还是 GitHub Pages #4

Closed TieBaMma closed 5 years ago

TieBaMma commented 8 years ago

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

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

StephDC commented 8 years ago

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

Lemmingh commented 5 years ago

@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 编译器（按首字母排序）

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

迁移前的准备工作

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

值得注意的是，需要在 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"> 页脚应该放在哪里？

超链接问题

本项目存在一些棘手的问题，比如超链接。目前，所有的链接默认都在当前页面的 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. 处置失效和重定向的链接

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

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

此外，有道云笔记似乎又更改了它们的 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 commented 5 years ago

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

然后，关于教程内容——

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

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

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

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

Lemmingh commented 5 years ago

@TieBaMma

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

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

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

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

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

所以我说

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

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

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

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

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

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

TieBaMma commented 5 years ago

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

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

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

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

同意。

HyperGroups commented 5 years ago

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

Lemmingh commented 5 years ago

@TieBaMma

非常感谢您的信任。

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

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

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

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

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

TieBaMma commented 5 years ago

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

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

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

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

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

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

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