Tutorial for ZJU-China 2024 WP Wiki
Note
两位好鸭！本仓库包含了 iGEM Wiki 官方框架，想提前熟悉一下的可以自取。
有疑问可以戳我，可以帮忙 debug 但不会帮忙写 hhh。
两位老师用于 WP 2024 施工的 GitHub 仓库（欢迎互相串门）
| Name | Repo | Site |
|---|---|---|
| YJL | iGEM24-WP-Tutorial | Here |
| YYW | Default | Here |
-
The final version of Wiki should be deployed as a
GitHub Pages Sitebefore 2024.02.24 0:00 -
HTML and all sort of source code MUST be committed to the Team Wiki repository on GitHub Repo
-
iframesare NOT allowed -
On every page, teams must add a clear and visible link to the team GitHub Repo
-
You can find the requirements for Wiki Pages @ here
-
These are URLs for all the Wikis created by ZJU-China:
You can visit other team's Wiki by modifiying the LAST part of the URL
- 2023: Flora Sentinel
- 2022: StoryLight
- 2021: ViruGuard
- 2020: MagHER2some
- 2019: PaDetector
- 2018: A Detector
- 2017: The Guardian Trichoderma
- 2016: Enigma
- 2015: Terminator
- 2014: GeneSocket
- 2013: The Ghost Kit
- 2012: RNA Scaffold
- 2011: Rainbofilm
- 2010: Bach
-
Best Wiki (Nominations) for recent years
-
Tutorial by UCAS-China (Not Required)
|__ static/ -> static assets (minified CSS & JS files) & some SVGs
|__ wiki/ -> Main directory for the pages and layouts
|__ footer.html
|__ menu.html
|__ layout.html -> Main layout
|__ pages/ -> Directory for all the pages
|__ *.html
|__ .github/
|__ workflows/
|__ build.yml -> Automated flow for building and deploying
|__ .gitignore -> which files/directories should be ignored
|__ README.md -> File containing the text you are reading right now
|__ app.py -> Python code managing your wiki
|__ freezer.py -> Python code for packing
|__ dependencies.txt -> Software dependencies from the Python code
Make sure that:
-
Git, Python3 & Virtualenv has been installed.
-
You have a GitHub account.
- Fork this Repo
Important
在 fork 时请 取消勾选 "Copy the master branch only" 选项
=> 这会导致在首次 push 前缺少 gh-pages 分支（问题不大，push 一次之后就会自动创建了）
-
Init Git Pages on branch
gh-pages进入
Setting->Pages，在Branch中选择gh-pages&/(root)并保存修改
-
Install
# clone the repository (with HTTPS) # OR you can just download the source code adn the extract it git clone [Code->Clone->Copy the Link] # create Python Virtual Environment cd iGEM24-WP-Tutorial python -m venv venv . venv/bin/activate # on Linux, MacOS; or . venv\Scripts\activate # on Windows
-
Launch
python app.py
Then, you can visit the home page @ http://127.0.0.1:8080 or http://localhost:8080.
-
Update
Simply
Commit & Push. All the modifications would be automatically to branch:gh-pages.You can see the result @
https://{Your Username}.github.io/iGEM24-WP-Tutorial/如果没有及时更新，可以：1. 查看有没有失败的 Action 2. 清空浏览器缓存
-
使用静态资源
如果您希望在项目中使用
/static路径下包含的静态资源，请确保引用路径符合以下规范：-
使用
<script>标签引入 JS 文件：-
声明相对路径
<script src="static/..."></script>
-
使用 flask API
<script src="{{ url_for('static', filename = '相对 static 的路径')}}"></script>
-
-
使用
<link>标签引入 CSS 文件：-
使用 flask API
<link href="{{ url_for('static', filename = '相对 static 的路径')}}" rel="stylesheet">
-
-
在
<body>标签内引入图片文件：-
手动声明相对路径
-
home.html下：<img src="static/...">
-
/wiki/pages下的其他文件：<img src="../../static/...">
-
-
使用 flask API（通用）
<img src="{{ url_for('static', filename = '相对 static 的路径')}}"> <!-- 二级路径用例 --> <img src="{{ url_for('static', filename = 'svg/logo.svg')}}">
-
原因详解
-
其实是因为
frozen-flask会把项目打包成以下形式：├── index.html # /wiki/pages/home.html │ ├── attributions # /wiki/pages/ 下的其他页面 │ └── index.html │ ├── ... │ └── static # /static 下的静态资源 └── ... -
flask 框架中的
{{ url_for('static', filename = '####')}}会自动替换为正确链接 -
手动输入相对链接则需要疯狂调整相对路径
-
-
部署失败
-
可能原因：由于
frozen-flask的特性，包含 不存在页面的相对路径 可能导致打包失败 -
建议：
请通过 注释
/wiki/pages/menu.html中的相对路径 （而非删除/wiki/pages下的 HTML 文件）来隐藏页面 -
debug 方法：
-
观察 Actions 中的错误输出
-
在项目根路径下运行
python freezer.py，观察报错信息
-
-
-
部署成功后无法即时应用修改
-
如果 Actions 中显示部署成功，则可能是 浏览器缓存 的锅
=> 建议手动清除缓存并刷新页面（或者直接换一个浏览器打开）
-
可以在项目根路径下执行以下命令：
python freezer.py
随后用 live Server 插件打开
/public/index.html文件（项目首页）=> 如果这里跑起来没问题，那就一定是缓存的锅
-
Beautiful and accessible math in all browsers
-
功能简介
MathJax 用于将 Latex 格式的公式转换为 SVG 图片显示，belike 从
\frac{1}{\pi i}变成$\frac{1}{\pi i}$ 事实上它支持非常丰富的 input/output 格式，可以自行爬去 官网 康康
-
使用简介
此处仅介绍 3.0 版本的 CDN 分法版本使用方式
本地 Release 版本的使用教程 & 按需加载就先咕咕了
有兴趣可以自己康康 3.2 版本的文档
-
简单的创建一个 HTML 文件
-
随便找个角落引入 MathJax 并进行配置
<script> MathJax = { tex: { // 支持 '$' 包裹行内公式，'$$' 包裹块级公式 inlineMath: [['$', '$']] }, svg: { fontCache: 'global' } }; </script> <!-- 因为国外的 CDN 有点慢，这里胡乱抓了一个国内的 --> <script type="text/javascript" id="MathJax-script" async src="https://cdn.bootcdn.net/ajax/libs/mathjax/3.2.2/es5/tex-chtml.js"> </script>
-
测试：在
<body>标签内随便打一些公式，观察是否能正常显示输入测试文本：
$$ x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a} $$应该显示为:
-
开始（并不）愉快地敲公式
=> 符号不会敲可以问浏览器（关键词请用 "Latex 公式"）
=> 也可以试试 VS Code 上的 Latex Workshop 插件