Total Pageviews

Showing posts with label pandoc. Show all posts
Showing posts with label pandoc. Show all posts

Monday, 10 February 2025

基于pandoc的静态网站生成器guxingke pages

 a static site generator, like hugo, hexo, but more lightweight. 

Pages

超轻量级的静态内容生成工具, 通过组合一些命令行工具构建而成。

核心逻辑在 makefile 和 helper 文件内,不超过 200 行。

功能

  • 博客
  • 静态 HTML 部署
  • Wiki 知识库
  • 自定义主题
  • 自定义所有流程

快速开始(macos 用户)

安装依赖

# jq 工具,处理 json
brew install jq

# yq 工具,处理 yaml
brew install python-yq

# sed ,使用 gnu-sed 而不是 macos 自带的。注意修改 PATH 
# PATH="/usr/local/opt/gnu-sed/libexec/gnubin:$PATH"
brew install gnu-sed

# pandoc , 用来实现 markdown 转 html , 核心工具
brew install pandoc

项目初始化

  • Clone 或者下载当前项目的源码
wget 'https://github.com/guxingke/pages/archive/master.zip'
unzip master.zip
mv master/pages-master pages
cd pages
  • 本地预览
make serve
  • 清除并重新构建
make clean && make

进阶功能

并行构建

项目基于 make 和 Makefile,并对并行构建进行了支持。

make -j 12 

解决全量构建时的速度问题

增量实时构建

watch 增量实时构建,并刷新当前 Chrome 的活动 Tab,基于 fswatch 在写入 3 秒后进行构建, 构建完成后通过 chrome-cli 刷新活动 tab (配合 make serve 使用)

make watch

切换主题

自带三主题,默认为 default。

make THEME=basic -j 12

使用主题 basic 进行构建。

集成 disqus 评论

只需反注释 basic.yml 文件中的 disqus 部分,配置 shortname 后重新构建即可。

部署新站点

  1. 修改 static/CNAME 文件内容,指向新的域名,或者移除该文件。
  2. 重新构建,或者移除 docs/CNAME 文件。
  3. 推送到新的仓库,并开启 Pages 服务。

更多功能

  • rss 支持
  • 搜索支持
  • 标签支持

实现原理

pandoc 转换工具

  • pandoc 支持模板
  • pandoc 支持读取 yaml 文件作为元信息
  • pandoc 支持 include 文件

make 构建

make 默认增量构建。

from https://github.com/guxingke/pages 

演示网站:https://www.guxingke.com/

 

Monday, 3 February 2025

Inkval - 基于 Pandoc 与 Bash 的静态网站生成器

 

项目地址:https://www.chunqiuyiyu.com/inkval/

示例博客:https://www.chunqiuyiyu.com/

为了摆脱 Hexo 所需 node_modules 中的一堆依赖,用 Shell Script 构建了这个项目。300 多行 10KB 左右的脚本满足了个人博客所需的所有特性:分页、RSS 、标签还有标签别名。生成网站的 Lighthouse 评分也没什么问题。

---------------------------------------------------------

Generating Static Sites with Pandoc and Bash

www.chunqiuyiyu.com/inkval/ 

Inkval GitHub code size in bytes

Features

  • Only based on Pandoc and GNU core utilities
  • Perfect score(100) on Google lighthouse
  • Easy to use and expand functions
  • Pagination support
  • Tag slug support
  • RSS support

For more information, visit website and docs.

Usage

curl -s https://raw.githubusercontent.com/chunqiuyiyu/inkval/main/inkval.sh | bash
# or
wget -qO - https://raw.githubusercontent.com/chunqiuyiyu/inkval/main/inkval.sh | bash

Tips

You should use last release Paondoc to avoid bugs and get better experiences.

(https://github.com/jgm/pandoc/releases/download/3.6.2/pandoc-3.6.2-windows-x86_64.zip 或安装版:https://github.com/jgm/pandoc/releases/download/3.6.2/pandoc-3.6.2-windows-x86_64.msi)

from https://github.com/chunqiuyiyu/inkval 

-----------------------------------------------------

我的补充说明:

登录linux vps.

首先安装 pandoc.

wget  https://github.com/jgm/pandoc/releases/download/3.6.2/pandoc-3.6.2-linux-amd64.tar.gz

tar xvf  pandoc-3.6.2-linux-amd64.tar.gz

 cd pandoc-3.6.2

root@racknerd-626f077:~/pandoc-3.6.2# ls
bin  share
root@racknerd-626f077:~/pandoc-3.6.2# cd bin
root@racknerd-626f077:~/pandoc-3.6.2/bin# ls
pandoc  pandoc-lua  pandoc-server

root@racknerd-626f077:~/pandoc-3.6.2/bin# echo 'export PATH=$PATH:/root/pandoc-3.6.2/bin' >> /etc/profile && source /etc/profile

root@racknerd-626f077:~/pandoc-3.6.2/bin# which pandoc
/root/pandoc-3.6.2/bin/pandoc
root@racknerd-626f077:~/pandoc-3.6.2/bin# cd ~

git clone  https://github.com/chunqiuyiyu/inkval 

cd inkval

 mv site/* ./

root@racknerd-626f077:~/inkval# ls
content  inkval.sh  LICENSE      README.md  site

layout     preview.gif  score.png
root@racknerd-626f077:~/inkval# chmod 755 inkval.sh

root@racknerd-626f077:~/inkval#  ./inkval.sh

root@racknerd-626f077:~/inkval# ls
content  inkval.sh  LICENSE      README.md  site
dist     layout     preview.gif  score.png
root@racknerd-626f077:~/inkval# cd dist

~/inkval/dist/里面有index.html,所以 ~/inkval/dist/就是静态网站的根目录。

不过 ~/inkval/dist/所展示的静态网站的效果很简陋。

root@racknerd-626f077:~/inkval/dist# cd ~

root@racknerd-626f077:~# git clone https://github.com/chunqiuyiyu/chunqiuyiyu.com

root@racknerd-626f077:~# cd chunqiuyiyu.com

root@racknerd-626f077:~/chunqiuyiyu.com# cp ~/inkval/inkval.sh ./

root@racknerd-626f077:~/chunqiuyiyu.com# ./inkval.sh (此即生成/更新静态网站的根目录的命令)

当前目录下,就会生成dist 目录。

~/chunqiuyiyu.com/dist/里面有index.html文件,说明

~/chunqiuyiyu.com/dist/就是静态网站的根目录,你可以绑定你的域名到该目录。(我是安装了nginx, 然后修改nginx的配置文件实现的。)

 不过还需要修改配置文件https://github.com/chunqiuyiyu/chunqiuyiyu.com/blob/main/content/index.md,把第7行的 link的值改为http://urdomain.com ,然后cd到~/chunqiuyiyu.com/,然后运行./inkval.sh即可。

项目地址:

https://github.com/chunqiuyiyu/inkval 

配置文件在哪里 · Issue #6

chunqiuyiyu/chunqiuyiyu.com

演示网站:http://cqyyc.smt.biz.st/


 


 

 


 

 

 

 

 

 

 

用 Makefile + pandoc + markdown 写博客

 

静态页面生成有很多工具,我用过 Jekyll, Hugo, Hexo 等等。我原来用 Jekyll 写笔记,其实也够用了。最近想画图,这个东西不能自动集成 metapost ,也是挺麻烦的。

这些静态网页工具,功能太多,有很多其实不需要,这的需要自定义一些功能,折腾这些架构又过于复杂。例如

  • 集成 metapost , dot 等画图工具。我自己读过一个别人写的 hexo plugin 支持 dot 集成,但是折腾一次很麻烦。
  • template 模式过于复杂,每个工具都有自己的一套自定义模板语言
  • 不支持 asciidoc 等混合格式。

本来我想继续使用 Jekyll 的,但是突然间需要让我升级 ruby , 然后升级 gem 然后升级 bundle ,然后升级 jekyll ,然后说有一个依赖关系找不到。 WTF

我不是 ruby 的专家。我不想折腾了。

Hexo 类似的问题,升级完 nodejs ,一大堆问题。

于是,我试着用原始的方法生成网页。类似 unix 下的哲学,每个工具完成一点点工作,然后把他们组合在一起。于是,我用到下面这些工具。

  • atom + markdown preview plus 支持编辑和预览
  • Makefile 管理生产方式
  • pandoc 处理 markdown 生产 html
  • asciidoc , 处理 asciidoc ,生产 html
  • MathJax 处理公式
  • metapost 处理画图。
  • perl 生产 index.html

需要安装

%  brew install mactex
% brew install pandoc
% apm install markdown-preview-plus

Makefile 一般 unix 系统都自带的。

first_blog.html: first_blog.md
    pandoc -s --output $@ $<

然后 make first_blog.html 就可以生成了。这下自由了,不需要安装一个编程语言环境,就可以搞定网页生成了。 而且每个模块是可以替换的。如果觉得 pandoc 不好,可以用 kramdown 等等其他命令行工具处理 markdown 。

我的 Makefile 比这个复杂一些,也是抄别人的。 感兴趣的可以

% git clone https://github.com/wcy123/wcy123.github.io
% git checkout pandoc

这里面每段代码都很简单,类似浆糊弄在一起。

css 我找了 solarized light scheme 。直接 copy paste 过去的。

Tuesday, 1 March 2022

latex排版

我最初写博客都是使用的是Markdown1,后来写书也使用Markdown做简单排版。但一到出版社编辑那儿,就必须用Word了。也跟出版社聊过,是否可以用Latex排版,但出版社的答复是养一个Latex排版师太贵了,因此,作者们还是需要使用Word排版。

对于那些写小说或故事的作者,或许用Word排版还是不错的,但是,对于像我这样的技术人员,由于书中有很多代码和图表,用Word排版就比较累,尤其是技术人员好多都在用Mac,与Windows版的Word兼容性还比较差,写起来就更痛苦了。

使用Markdown格式写作,比Word要轻松多了,同时,使用一些辅助工具也能做到比较好的排版。如果万一有一天写出来的书能够正式出版,也希望Word是最后一步,把痛苦留到最后。

Word有一个功能确实不大好替代,那就是『修订』功能,使用它可以让作者和编辑很方便地交互修改文件。但文件传来传去也很烦。不知道一些在线的协作工具如石墨文档等,是否适合这种协作。

当然,其实作者不应该关注排版,而是在保证内容正确的前提下,把章节、强调、引用、代码之类的都标注出来即可,出版社是有专人进行排版的。而做这些标注,Markdown就够了。而且Markdown文件可以很方便地放到Git仓库中。我们不期望出版社所有的编辑也能熟悉Git,但如果真有哪天编辑们也喜欢Git了,那社会就真的进步了。

关于排版,本书主要讲一下相关的模板,以及一些排版原则:

  • 支持标准的Markdown,暂不支持各种扩展;
  • 使用开源字体;
  • 代码应该有单独的格式,用等宽字体,最好支持语法高亮;
  • 应该有移动版,目前大多数PDF并不适合在手机上阅读;
  • 移动版不应该首行缩进,因为页面太窄,缩进反而影响阅读体验;
  • 标准版应该首行缩进;
  • 印刷版应该奇偶页不同;
  • 提供Word版方便与其它人交流;
  • 还可以生成EPUB电子书等其它格式,欢迎提pr。

本书是可以『自举』的,也就是说你可以通过本书的源代码生成本书的PDF。参见:

https://github.com/seven1240/latex

最后,本书写作的目的并不是教你成为一个排版专家,相反,希望通过分享我的排版模板,让广大技术人员专注于用自己喜欢的工具写好自己的作品,忘记排版 ;)。

from https://github.com/seven1240/latex

-------------------------------------------------

编辑排版系统LaTeX

LaTeX是一款开源的编辑排版系统,由美国计算机学家莱斯利·兰伯特(Leslie Lamport)在20世纪80年代初期开发。基于TeX格式化引擎,LaTeX通过\section和\paragraph等语句,规定了每一句话在文章中所从属的层次,方便对各个层次批量处理。与Word相比较,LaTeX拥有方便美观的数学公式编辑、不会乱动的退格对齐。利用这种格式,可以方便生成复杂表格和数学公式,生成从简单的信件到完整书籍的各种类型的文档。