如何搭建 Markdown 网页写作环境?

/ 归类于 日常, 技术 / 目前尚无评论

标题也许叙述很迷,我想要说的是,如何用 Markdown 来写网页。当然,对于一般的 PHP Markdown 解析器来说,转义是非常简单的(但是代码会很复杂)。因此,我们需要

具体的,在开头不会再度供述,详情可以往下观看。如果你所想要制作的是类似于 Gitbook 那样响应式的电子书,那么本文也许可以满足你的需求。

简介

搭建 Markdown 协作环境,是一个非常模糊的描述方法。我们可以把它拆开来理解。首先我们先明白我们的网页分成哪些部分。如果按照本文的内容来说,我们的网页应该是包含网页主体解析代码/框架(包括处理请求)CSS 样式表主要内容文本的。

网页主体

主体可以简单地理解为一个模板,即我们在编写内容的过程中不会改变的那一部分。因为我们所要写的是电子书,因而 Sidebar,DefaultPage 和 Appbar 就是我们的主体构成部分。

Sidebar

Sidebar 是用户选择阅读内容的方式,我们通过 Sidebar 来呈现网页的所有内容。它相当于是一个目录。通常地,我们把它叫做抽屉式菜单,尽管它的中文叫做“侧边栏”。

DefaultPage

DefaultPage 可以分为两种,一种为 DefaultPage(真正意义上的),另外一种是 ErrorPage。相对于 DefaultPage,ErrorPage 使用起来会更加严谨,而 DefaultPage 使用起来会更加友好。

广义上的 DefaultPage 是指在遇到错误(但并不是路径、网址等错误,仅仅是请求错误)或者空请求的时候所显示的网页。狭义上的 DefaultPage 是指无论遇到的是错误还是空请求,都会自动跳转到一个默认的页面。这就相当于

<?php
// window.location.href = "https://test.com/index.php?content=it-is-not-exist"
$request = $_GET['content'];

if (empty($request)){
    defaultPage();
// 假设此处是直接以 $request 作为文件名,这与后文的实现思路一致
} else if (!file_exists("/documents/".$request.".md")){
    defaultPage();
} else {
    $content = file_get_contents("/documents/".$request.".md");
    $output = parse($content);
}
?>

而 ErrorPage 则不一样。在遇到错误请求和空请求的时候,什么页面也不会呈现,对此我们可以规定一个专属的错误页面来警告用户,这是一个错误的请求。这就好比把以上代码中的 defaultPage(); 修改为调用指定错误页面的函数。

Appbar

Appbar 具有特色,因为针对不同的设计规范对 Appbar 的应用不一样。MD 设计规范中,对 Appbar 的应用有且仅有 Toolbar 一种。但是如果是其他的规范(比如本博客的主题 Pinghsu,Appbar 上就呈现了“页面”这样一个独有的元素),那么情况就不一定了。

Appbar 也可以不要,但是为了布局的匀称和设计美学,很多情况下它是必须的(无论是 PC 端还是移动端)。

解析代码和框架

解析代码和框架是网站真正的主体——只不过是在后端而已。在这个环节中我们规定以何种方式对内容进行读取。我们可以像上文所描述的那样:

$content = file_get_contents("/documents/".$request.".md");

以请求的名称来命名文件,这样就可以避免循环语句,仅仅依靠请求内容就可以指定要访问的文件,随即进行读取。同时这样,我们为了保证地址栏的干净整洁,也不得不采取规范来命名处于后端的文件(其实不应该叫做后端,叫做“存储在服务器的某个地方”才对)。

以上代码可以实现诸如index.php?contents=intro时显示指定目录下名为intro.md文件的内容。

这样我们指定了文件的内容,随即我们就可以开始解析了(什么?你居然告诉我你想直接访问.md文件?!)。本文中以 Parsedown 来举例。

首先我们按照官方的说法,将解析的过程封装成一个函数:

function parse($content){
    $Parsedown = new Parsedown();
    echo $Parsedown->text($content);
}

// 如果你很讨厌传参,可以这样写,但是上面的部分就要改了:
function parse($path){
    $Parsedown = new Parsedown();
    echo $Parsedown->text(file_get_contents($path));
}

然后我们就可以结合上面的读取文件,来写成一个“依据用户请求的内容来解析并呈现相应 Markdown 文件解析成 HTML 元素”的函数。

// 以下是完整程序
$request = $_GET['content'];
// $path 的规定依据实际路径来写
$path = "/documents/".$request.".md";

function parse($path){
    $Parsedown = new Parsedown();
    echo $Parsedown->text(file_get_contents($path));
}

function getContents(){
// 注意:对于这种函数,建议不写参数列表。
    global $request;
    global $path;
    // 一定要记得 global!我被这个问题困了一天。
    if (!empty($request)){
        if (file_exists($path)){
            parse($path);
        } else {
        // do something warning.
        // OR defaultPage();
        }
    } else {
        // do something warning.
        // OR defaultPage();
    }
}

其实我不确定我写的是不是对的。就这样,一个简单的解析框架就完成了。接下来在正文中<?php getContents();?>调用它即可。

CSS 样式表

这个不多说,纯粹是为了规定内容。因为诸如 Parsedown 的 PHP Markdown 解析器,解析出来的元素都是纯元素(比如<p>This is a pure element</p>),那么自然就没有样式。因此我们可以自写一个 CSS 类,将<?php getContents();?>放置到一个<div>下面,再在这个<div>上摆上我们写好的类,即可对文本进行格式化。

一个比较好懂的例子,在 MDUI 前端框架中有一个叫做mdui-typo的类,于是这样写:

<div class="mdui-typo">
    <?php getContents();?>
</div>

那么我们所解析出来的内容就会被自动赋予样式。如果需要特殊规定,直接在<style>标签里设置即可。

主要内容文本

主要内容文本,为了切题,那么我们使用 Markdown 来编写。怎么编写?你肯定需要了解 Markdown 的语法。我抽空可以写一写 Markdown 的语法,到那时候我会把链接放在这里。

你只需要参考上方的代码,按照你自己给自己定下的规范(比如请求内容和文件名相同)来设置文件名,然后按照日常写 Markdown 的方式去写即可。一个成功的例子:

一个成功的例子

总结

如果你仍然没有看懂,或者不知道怎么写又想写,可以联系我。我可以提供源代码。

这只是一个思路。对于一般的解析,以及电子书类,这是最基础的方法。再者,如果要呈现更好的效果(比如请求独立,或者无请求呈现 by JavaScript),就不会用到这种办法了。

总之,这是一种逃避纯静态的面向新手的一种很好的办法,虽然非常土,但是够用了。

评论 / 您目前尚未登录立即注册