Skip to content

使用Markdown制作和蒋炎岩老师幻灯片同一主题的Web幻灯片框架(base on Reveal.js)

License

Notifications You must be signed in to change notification settings

lovelxc/jyyslide-md

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

92 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

jyyslide-md

一款通过简约的Mardown方言生成具有南大蒋炎岩老师幻灯片风格的Web幻灯片转换工具
准确的说是一款基于Reveal.js的定制主题Web幻灯片框架(类似reveal-md,不过定制主题和蒋老师的一样)。

Background | Install | Usage | Grammer | Example | Develop | Acknowledgement | License

Background

可以从奥卡姆剃刀(如无必要,勿增实体)的角度考虑我开发本项目的发心。

说起幻灯片,首先想到的是微软的PowerPoint,PPT几乎成了幻灯片的代名词。但是在使用过程中我们会发现,它提供的很多的功能,为了使用这些功能需要很高的学习成本,但大多数场景我们用不到这么多功能;同时在使用别人的PPT模板是因为我们对功能的不熟练而不能展现模板PPT的全部效果。在幻灯片领域有类似Markdown之于Word的框架嘛?

除了能量点这样的制作幻灯片的软件外,还有基于Web的幻灯片,我基本都尝试了一下。但是并没有完全满足我的要求的。

南京大学蒋炎岩老师开源了他的操作系统课程,相信上过他的课的同学除了会被他深入浅出的授课所折服外,也一定对他的幻灯片感兴趣。他的幻灯片是基于Reveal.js这款Web幻灯片框架,但不清楚他具体是如何制作的,在经过他的同意下,我制作了这个将Markdown方言转换成和他一个风格的幻灯片的工具。

对于Markdown扩展语法的设计尽可能简单,有些功能不是不能提供,但是提供会导致语法没有性价比的扩张,所以舍弃。让设计尽可能足够且简约。

Install

本项目使用Python开发,模块管理使用Poetry,请确保您的机器上有版本足够的Python(3.10以上)并安装有第三方模块Poetry,同时也得益于Python,本项目应该可以运行于任何系统上。

关于Poetry可参考我的笔记,当然下面会提供足够的用法。

  1. 克隆项目到本地并进入:
    git clone https://github.com/zweix123/jyyslide-md.git
    cd jyyslide-md
  2. 利用Poetry下载第三方模块
    python3 -m poetry install
    # 或者 poetry install

如果在win机器且出现乱码, 可以尝试下面的方案
控制面板 -> 区域 -> 管理 -> 更改系统区域设置 -> 打开Beta版

Usage

请确保已经Install好了

  • 使用Peotry管理的Python有两种运行方式
    1. 进入虚拟环境:

      python3 -m poetry shell
      # 或者 poetry shell

      之后就可以正常的运行Python代码了

    2. 使用前缀:在运行Python代码的命令前添加python3 -m poetry run(或者poetry run

      比如样例1中的命令应该是poetry run python main.py example\jyy\操作系统概述.md

命令格式如下

python main.py [Markdown文件]

在Markdown文件同级目录会出现一个dist文件夹,其下有一个index.html文件和一个static文件夹,前者即为生成的“Web幻灯片,static即为其相关静态文件。网页的title和Markdown文件同名、icon即为static/img/favicon.png,可通过替换这个文件修改icon。

Grammer

教程:在这里可以结合效果来说明语法(推荐

这个幻灯片就是用jyyslide-md制作而成的

  • 水平幻灯片使用\n---\n(三个)分割

  • 垂直幻灯片使用\n----\n(四个)分割

  • 渐变垂直幻灯片使用\n++++\n(四个)分割

  • 在同一张幻灯片中依次出现的部分使用\n--\n(两个)分割

  • 作者信息使用\n+++++\n(五个)和正文分割,使用Json格式
    这里主要指指的是这部分

    因为这部分是多个文字、图片、链接为一体,如果使用扩展Markdown语法的设置会让语法很凌乱。
    实际上这样的页面只在第一页出现,即使不使用这样的语法,使用这样的形式

    # Title
    
    >author
    

    在大多数场景也足够,所以从设计上将这部分从主题抽离出来

    这部分的格式如下,

    例子中的jyy中的Markdown文件

    {
        "author": {
            "name": "蒋炎岩",
            "url": "https://ics.nju.edu.cn/~jyy/"
        },
        "departments": [
            {
                "name": "  南京大学  ",
                "url": "https://www.nju.edu.cn/main.htm",
                "img_url": "./img/nju-logo.jpg"
            },
            {
                "name": "计算机科学与技术系",
                "url": "https://cs.nju.edu.cn/main.htm",
                "img_url": "./img/njucs-logo.jpg"
            },
            {
                "name": "计算机软件研究所",
                "url": "https://www.nju.edu.cn/main.htm",
                "img_url": "./img/ics-logo.png"
            }
        ]
    }
    

  • 对Markdown原生语法适配情况:

    这里使用的Markdown语法使用的是严格语法。

    • 文字格式:

      • 通过Markdown原生语法支持加粗斜体
      • 通过插入html支持删除线高亮、标红
    • 支持注释

    • 支持列表

    • 支持代码和代码高亮

      Reveal-md和Slidev支持的代码特定行高亮暂时不支持

    • 支持引用(链接和图片),图片推荐以插入HTML的方式使用

      <img src="图片地址">

      这里的src支持URL,相对地址和绝对地址,程序会将其down或者copy到dist下的img中

      这里使用的爬虫是非常简单的爬虫,建议自己下载到本地使用。

      • 图片居中:
        <img class="float-right" src="图片地址">
      • 图片右对齐:
        <img class="float-right" src="图片地址">
        Markdown中的格式是流的形式,即图片是占位的,这里默认左对齐和居中的图片都是占位的,但是右对齐的图片不占位

      其他格式调整SFTW

    • 支持数学公式

    • 支持表格(表格的格式并不好看)

    • 关于Markdown的这个语法:大于三个的-是分割线<hr>,我们发现这和扩展语法冲突,所以这里是大于四个的-是分割线,且这里的分割线在HTML中是空行的效果


  • 调整主题:如果您有CSS基础,可以调整蒋老师主题(主要指字号、字间距、行间距之类的微调),关于蒋老师主题的CSS文件在dist/static/jyy/jyy.css中。

蒋老师有而未设置专门语法的部分

  • 多个幻灯片并列

    <center>
    <img class="inline" ...>
    <img class="inline" ...>
    <img class="inline" ...>
    </center>
    

    如果你想,你可以直接在Markdown中插入类似上面的代码

  • 插入B站

Example

  • example/jyy/操作系统概述.md即为蒋老师2022年的第一节课

    python main.py example\jyy\操作系统概述.md  # win
    python main.py example/jyy/操作系统概述.md  # linux

    打开example\jyy\dist\index.html即可查看

  • example/Intro/slide.md即为本项目介绍的幻灯片

    python main.py example\Intro\slide.md  # win
    python main.py example/Intro/slide.md  # linux

    打开example\Intro\dist\index.html即可查看

Develop

  • 根目录下的main.py是项目的入口,主体代码在src目录下,逻辑核心在converter.py,这个过程要维护很多配置信息和全局信息,所以我将其放在settings.py下,util目录则是些辅助函数
  • 不建议扩展标记,converter虽然不长,但是写的不是很优雅,可维护性低
  • 推荐从src/util/md_util.py入手,项目将Markdown转换成html的代码在这里,可以通过修改markdown模块相关来增加功能
    • 比如slidev的代码特定行高亮,这就是后续的开发计划
  • 格式化使用black,静态检查使用mypy
    • 依赖库中有很多用于静态检查的模块,如果想最小化本项目,可以重新加载依赖
      • 这个模块pygments,没有出现在代码的任何地方,但是在代码高亮中发挥重要作用,如果重新加载依赖,不要忘记它。

Acknowledgement

License

MIT © Richard Littauer

About

使用Markdown制作和蒋炎岩老师幻灯片同一主题的Web幻灯片框架(base on Reveal.js)

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Python 50.2%
  • CSS 26.6%
  • HTML 23.2%