gitpitch做快速演示

工具
, , ,

相信很多时候,技术汪是不会喜欢每天做表格,写word,改paper格式,以及头疼的做presentation演示的…特别是有选择强迫症的时候,调来跳去浪费时间,还是喜欢markdown,LaTex这种专注写作本身的.今天就来说说快速通过markdown-->演示文档的工具,gitpitch 文档参考.

0x00.介绍

这工具无需下载安装,在线生成,离线可以利用各种http服务器加载html页面.也很方便.简单入门介绍见官方文档,不再重复. 这里主要说一下快速上手的要素以及把文档中常用的重点举例说一下.以便可以更快的上手. (效果参考),这里我列一下要点:

  • 快速构建
  • 调整配置/主题
  • 改markdown笔记为展示
  • 存在的问题

0x01.快速构建

快速构建参考官方的60s构建gitpitch,在任何github项目添加个PITCHME.md 文件即可渲染.然后地址稍换一下就是在线的演示了,如果想离线使用下载下来.然后通过web服务器加载即可. 推荐做法是用py/go自带的简易http-server:

1
2
#py3下,在下载后的index.html文件路径
python -m http.server #然后访问默认的localhost:8000端口即可.

离线也很简单,而且如果担心信息泄露可以删掉之前git仓库上的.(虽然感觉略蠢).

它还支持一个单独的yaml文件来进行其他的渲染或者设置. 建议直接下一个主题模板,里面有写好了的yaml文件,在那基础上调整即可. (推荐brick跟旁边的那几款,还算比较舒服)

0x02.修改配置

在普通电脑上有个很严重的问题,就是字体过大.(本质是因为它是展示的,不是用来放一堆文字的)然后它自动居中了导致很多地方看起来很奇怪,找了半天没有看到设置字体的选项…. 那估计是要修改css文件了? (有什么好办法也可以告知)

更新:

修改assert文件夹中的 PITCHME.css文件在根目录,然后设置字体… (虽然我觉得这样太臃肿了一点

然后再yaml文件中设置theme-override : assert/css/PITCHME.css 即可. (位置可变,但是不建议放根目录下) 不过实际过程中发现修改css很蛋疼,因为一改全改了.导致其他地方又要自己写行内样式…暂时不知道有没有什么好的写好的了css,附上我自己的简陋版yaml文件跟css: (希望有人给个好用的css..)

1
2
3
4
5
6
7
8
#PITCHME.yaml
theme : beige
slide-number : true
theme-override : assets/css/PITCHME.css  
highlight : hybrid
logo : assets/image/logo.png
transition : none
published : true

PITCHIME.css

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
.reveal {
    font-size: 28px; /* 核心修改但是这样会全部一起变大变小,过粗暴. */
}

.h2 .h3 .h4 {
    font-size: 40px;
}

.reveal pre {
  width: 100%;
}

.reveal pre code {
  font-size: 1.4em;  /*1.2em deafult*/
  line-height: 1.2;
  max-height: 70vh !important; /*50vh deafult*/
  opacity: 0.90;
  border-radius: 10px;
}

.reveal .slides section .code-presenting-annotation {
  color: white;
  background: black;
  padding: 1px 15px;
  border-radius: 15px;
  opacity: 0.75 !important; /* 0.75 不透明度*/
  font-size: 65% !important; /* 50% deafult*/
}

.reveal p span.slide-title {
  color: white;
  background: black;
  padding: 4px 15px;
  opacity: 0.75 !important;
  border-radius: 15px;
}
.reveal div.left {
    float: left;
    z-index: -10;
    width: 45%;
}

.reveal div.right {
    float: right;
    z-index: -10;
    width: 55%;
}

.reveal a.pro-link {
    color: white;
    font-size: 0.4em; /*0.5em deafult*/
}

#title-footer {
  color: white;
  background: black;
  opacity: 0.65 !important;
}

#title-footer p.footer-hard {
    color: #b6b6b6;
}

#title-footer p.footer-fade {
  color: #b6b6b6;
}

#gp-logo img {
  max-height: 0.2em; /*2em deafult*/
  max-width: none;
}

.white {
  color: white;
}

.gp-tip { font-size : 1.3em; } /*1.5em deafult*/

.gp-contact { font-size : 1.1em; } /*1.4em deafult*/

.gp-download { margin-left: 5px; }

0x03.技巧

  • 最重要的一条,不要使用符合样式表,否则大部分gitpitch语法都会出问题.

  • @title[xx] 语法是设置右侧的导航栏的名字…我觉得没有必要的话不用设置多了

  • 大量的<span> 标签可以设置颜色字体之类的东西…但是我觉得很蛋疼.

  • @fa[arrow-down] 标签可以添加个向下的箭头↓ 同理,可以有上左右,修改英文即可..建议使用,但是放到模板里面

  • @[a,b](这部分代码的说明) 用于代码部分高亮,如果多行支持a-b 的语法,可组合使用,列在一起有切换的效果

  • 创建开发分支,并学会合并到master..

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    #1.创建并切换到开发分支
    git checkout -b dev   #新的分支名

    #2.如果要合并到master
    git checkout master
    git merge --squash dev #也能用rebase?  这样可以保证提交历史干净.

    #3.正常提交 add-commit-push

    #补充:如果想直接下某个分支代码
    git clone -b dev https://xxx   #加 -b branchName 即可

  • 字体默认会自动居中,所以注意不要丢长篇文字在一起

  • 有时候你分割不好,字体会超出,记得提前预览,然后一面不要放太多东西,或者改小字体.

  • 可以直接从git仓库中加载代码到演示中,使用语法---?code=path/xxx

    1. 可以加入&title= xx 补充为代码块的文字标题. (推荐)

  • 推荐的主题是beige ,sky 也还行,非主流的注意注意字体跟背景重叠会很糟

  • 表格千万要注意…. 空格渲染的问题,就是说不要随便在列表里面嵌套表格. 后果灾难性严重

  • 如果需要给有序/无序列表给ppt那样的逐条播放,使用@ul @ulend (无序) 以及@ol @olend (有序). 但是注意嵌套的列表/代码快无法支持. (所以很蛋疼)

  • 而言在yaml文件里面设置autoslide : 5000 (5s)自动轮播幻灯片,如果想单独设置某张可以参考文档

  • 不要使用两个> 引用, 不要使用很长的列表/表格/图/文字段落,因为都识别不好.

  • 代码段的使用是最好的功能之一,但是如果直接写会发现首先会放一次全部高亮的代码,暂时不知道如何避免.. 建议把代码高亮放代码快下方. 例如 code{} @(1~3,5)[xx] .

  • 演示功能很有用 Note: 下面接的内容都可以作为演示,支持列表之类的. 建议放在每张图的最后,不过不知道是否支持离线(待确认.)

0x04.避坑

gitpitch的理念很好,但是目前还有不少小问题,但是大部分可以到处找来找去之后勉强解决,但是很浪费时间,我列一下:

  • gitpitch默认是跟github绑定的,所以你如果你要使用公网gitlab或gogs . 则需要手动在之前的地址之后加?grs=gitlab .或者其他,但是非常坑爹的是没有gogs的示例. 然后我用gogs账户的话怎么都渲染不出来…. 以后准备提交个issue问问. (目前测试结果是不支持gogs渲染 或 关键字错误)
  • 图片相对跟绝对路径貌似离线的时候都可以导出为离线图片. (待确定)
    1. 但是要注意,不能使用默认的\ 作为相对路径, 而是用/
    2. gif图片同样支持
  • 文字大小不能通过浏览器缩放放大改变,而需要修改PITCHME.css
  • 不要在master分支上直接push变动,因为缓存默认认为master稳定的机制,可能需要等好几分钟gitpitch网站才会同步github的更新. 如何使用分支参考
  • 在标签列中慎用分隔符 (读取不出来+++或者---) 因为前面有多个空格,如果手动删掉空格整个代码段会出错.
  • 导出为PDF/离线渲染是使用最多的之一,因为很多时候不方便在线使用. 但是根据我使用经验来看,失败率非常之高…. 很可能是因为服务器在US的原因(但是且xxn到US还是会经常报错,看了官方issue,很可能是空格图片名或者很图片尺寸超出.) 强烈建议先离线下好
  • 如果考虑安全起见,强烈建议还是本地自建gogs服务然后放心用(详情见下一篇文章)