Git Product home page Git Product logo

md2report's Introduction

md2report

一个用于将Markdown文件转换为可以直接提交给学校的实验报告/大作业报告/期末小论文的工具。

如果你的院系/课程要求必须提交docx格式的报告,并且:

  • 你认为word/docx实在是太蠢了,并且习惯于使用markdown编辑文档,md2report能够大幅缩短你在报告格式、docx样式以及排版上花费的时间;
  • 你没有试过使用markdown,不妨尝试一下: Markdown Guides, Mardown 教程

如果你的院系/课程允许提交pdf格式的报告,寻找一个好用的tex模板或许是一个更好的方案。但是考虑到学习成本以及使用难度,md2report仍然可以作为一个替代选项。

预览更多

Preview

Quick Start

虽然md2report使用的都是标准markdown语法,但是markdown标记到docx的样式映射可能与你的习惯不同。 因此,请确保除了本小节内容以外,开始使用md2report之前先阅读文档中关于语法的部分。

Web UI

md2report提供了Web UI, 无需安装即可使用。

CLI

md2report提供了CLI,如果想使用CLI,需要:

  • python 3.10+
  • poetry in PATH
  • pandoc in PATH
  • Git LFS installed
git clone https://github.com/woolen-sheep/md2report.git 
cd backend
poetry install
poetry shell

python md2report.py -h
# usage: md2report.py [-h] [-c CONFIG] [--highlight HIGHLIGHT] [-o OUTPUT] -i INPUT [-t TEMPLATE]
#
# options:
#   -h, --help            show this help message and exit
#   -c CONFIG, --config CONFIG
#                         config file path
#   --highlight HIGHLIGHT
#                         enable highlight of code blocks
#   -o OUTPUT, --output OUTPUT
#                         output docx filename
#   -i INPUT, --input INPUT
#                         input markdown filename
#   -t TEMPLATE, --template TEMPLATE
#                         template to use
#
# Args that start with '--' (eg. --highlight) can also be set in a config file (specified via -c). Config file syntax allows:
# key=value, flag=true, stuff=[a,b,c] (for details, see syntax at https://goo.gl/R74nmi). If an arg is specified in more than
# one place, then commandline values override config file values which override defaults.

python md2report.py -i test/test_case/5.2数据结构实验报告.md

# see output.docx

Docker

docker run --name md2report -d woolensheep/md2report:latest

此docker为 backend/Dockerfile build 产物,无法作为完整的前后端使用。但是你可以进入其中运行CLI而无需搭建环境:

➜  no-more-docx-report git:(master) ✗ docker exec -it md2report bash
root@f35bd61ef8bc:/app# python md2report.py -h
usage: md2report.py [-h] [-c CONFIG] [--highlight HIGHLIGHT] [-o OUTPUT] -i INPUT [-t TEMPLATE]

options:
  -h, --help            show this help message and exit
  -c CONFIG, --config CONFIG
                        config file path
  --highlight HIGHLIGHT
                        enable highlight of code blocks
  -o OUTPUT, --output OUTPUT
                        output docx filename
  -i INPUT, --input INPUT
                        input markdown filename
  -t TEMPLATE, --template TEMPLATE
                        template to use

Self-Hosted Web UI

md2docx的Web UI也是开源的,你可以使用docker-compose部署。 需要注意的是现在的docker-compose.yaml中挂载了绝对路径,使用之前请先修改。

cd backend
docker compose up --build -d
docker compose ps

Features

目前支持的特性如下:

  • Title and SubTitle
  • Abstract
  • Heading (H1 to H4)
  • Image Caption
  • Table
  • Table Caption
  • Code Highlight
  • Table of Content
  • Header and Footer
  • Page Numbering
    • Skip numbering of TOC and Abstract
  • Template of Specific School
    • HUST
      • School Logo
      • Student Infomation

由于依赖了pandoc,除了以上内容,pandoc原生支持的markdown语法也应该正常工作。

Compatibility

目前仅在MS Office 2019上进行过测试,测试版本为Microsoft® Word 2019MSO (版本 2210 Build 16.0.15726.20070) 64 位,能够正常打开生成的文档。 打开文档时若提示是否更新文档中的这些域?,请选择。另存文件可以消除该提示。

Contribute

在open issue之前请先阅读提问的智慧

我不确定是否只有我所在的学校存在报告过多的现象,或者这是一个普遍的现象。如果你有同样的困扰,可以开PR来补充你们学校的template。

md2report's People

Contributors

woolen-sheep avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.