• 设为首页
  • 点击收藏
  • 手机版
    手机扫一扫访问
    迪恩网络手机版
  • 关注官方公众号
    微信扫一扫关注
    迪恩网络公众号

rhwilr/markdown-documentation-template

原作者: [db:作者] 来自: 网络 收藏 邀请

开源软件名称(OpenSource Name):

rhwilr/markdown-documentation-template

开源软件地址(OpenSource Url):

https://github.com/rhwilr/markdown-documentation-template

开源编程语言(OpenSource Language):

TeX 96.7%

开源软件介绍(OpenSource Introduction):

Pandoc document template

Description

This repository contains a simple template for building Pandoc documents; Pandoc is a suite of tools to compile markdown files into readable files (PDF, EPUB, HTML...).

Usage

Installing

In order to use this makefile you will need to make sure that the following dependencies are installed on your system:

  • GNU make
  • Pandoc
  • LuaLaTeX
  • DejaVu Sans fonts

Folder structure

Here's a folder structure for a Pandoc document:

my-document/     # Root directory.
|- build/        # Folder used to store builded (output) files.
|- src/          # Markdowns files; one for each chapter.
|- images/       # Images folder.
|- metadata.yml  # Metadata content (title, author...).
|- Makefile      # Makefile used for building our documents.

Setup generic data

Edit the metadata.yml file to set configuration data:

---
title: My document title
author: Ralph Huwiler
rights:  Creative Commons Attribution 4.0 International
language: en-US
tags: [document, my-document, etc]
abstract: |
  Your summary text.
---

You can find the list of all available keys on this page.

Creating chapters

Creating a new chapter is as simple as creating a new markdown file in the src/ folder; you'll end up with something like this:

src/01-introduction.md
src/02-installation.md
src/03-usage.md
src/04-references.md

Pandoc and Make will join them automatically ordered by name; that's why the numeric prefixes are being used.

All you need to specify for each chapter at least one title:

# Introduction

This is the first paragraph of the introduction chapter.

## First

This is the first subsection.

## Second

This is the second subsection.

Each title (#) will represent a chapter, while each subtitle (##) will represent a chapter's section. You can use as many levels of sections as markdown supports.

Links between chapters

Anchor links can be used to link chapters within the document:

// src/01-introduction.md
# Introduction

For more information, check the [Usage] chapter.

// src/02-installation.md
# Usage

...

If you want to rename the reference, use this syntax:

For more information, check [this](#usage) chapter.

Anchor names should be downcased, and spaces, colons, semicolons... should be replaced with hyphens. Instead of Chapter title: A new era, you have: #chapter-title-a-new-era.

Links between sections

It's the same as anchor links:

# Introduction

## First

For more information, check the [Second] section.

## Second

...

Or, with al alternative name:

For more information, check [this](#second) section.

Inserting objects

Text. That's cool. What about images and tables?

Insert an image

Use Markdown syntax to insert an image with a caption:

![A cool seagull.](images/seagull.png)

Pandoc will automatically convert the image into a figure (image + caption).

If you want to resize the image, you may use this syntax, available in Pandoc 1.16:

![A cool seagull.](images/seagull.png){ width=50% height=50% }

Also, to reference an image, use LaTeX labels:

Please, admire the gloriousnes of Figure \ref{seagull_image}.

![A cool seagull.\label{seagull_image}](images/seagull.png)

Insert a table

Use markdown table, and use the Table: <Your table description> syntax to add a caption:

| Index | Name |
| ----- | ---- |
| 0     | AAA  |
| 1     | BBB  |
| ...   | ...  |

Table: This is an example table.

If you want to reference a table, use LaTeX labels:

Please, check Table /ref{example_table}.

| Index | Name |
| ----- | ---- |
| 0     | AAA  |
| 1     | BBB  |
| ...   | ...  |

Table: This is an example table.\label{example_table}

Insert an equation

Wrap a LaTeX math equation between $ delimiters for inline (tiny) formulas:

This, $\mu = \sum_{i=0}^{N} \frac{x_i}{N}$, the mean equation, ...

Pandoc will transform them automatically into images using online services.

If you want to center the equation instead of inlining it, use double $$ delimiters:

$$\mu = \sum_{i=0}^{N} \frac{x_i}{N}$$

Here's an online equation editor.

Output

This template uses Makefile to automatize the building process. Instead of using the pandoc cli util, we're going to use some make commands.

Export to PDF

Use this command:

make pdf

The generated file will be placed in build/pdf.

Please, note that PDF file generation requires some extra dependencies (~ 800 MB):

sudo apt-get install texlive-latex-base texlive-fonts-recommended texlive-latex-extra 

Export to EPUB

Use this command:

make epub

The generated file will be placed in build/epub.

Export to HTML

Use this command:

make html

The generated file(s) will be placed in build/html.

References




鲜花

握手

雷人

路过

鸡蛋
该文章已有0人参与评论

请发表评论

全部评论

专题导读
热门推荐
阅读排行榜

扫描微信二维码

查看手机版网站

随时了解更新最新资讯

139-2527-9053

在线客服(服务时间 9:00~18:00)

在线QQ客服
地址:深圳市南山区西丽大学城创智工业园
电邮:jeky_zhao#qq.com
移动电话:139-2527-9053

Powered by 互联科技 X3.4© 2001-2213 极客世界.|Sitemap