diff --git a/Makefile b/Makefile index ce51703..4b77479 100644 --- a/Makefile +++ b/Makefile @@ -2,20 +2,32 @@ # Configuration #################################################################################################### +# Build configuration + BUILD = build MAKEFILE = Makefile OUTPUT_FILENAME = book METADATA = metadata.yml CHAPTERS = chapters/*.md TOC = --toc --toc-depth=2 +METADATA_ARGS = --metadata-file=$(METADATA) IMAGES_FOLDER = images IMAGES = $(IMAGES_FOLDER)/* COVER_IMAGE = $(IMAGES_FOLDER)/cover.png MATH_FORMULAS = --webtex CSS_FILE = style.css -CSS_ARG = --css=$(CSS_FILE) -METADATA_ARG = --metadata-file=$(METADATA) -ARGS = $(TOC) $(MATH_FORMULAS) $(CSS_ARG) $(METADATA_ARG) +CSS_ARGS = --css=$(CSS_FILE) + +# FILTER_ARGS = --filter pandoc-crossref +# DEBUG_ARGS = --verbose + +ARGS = $(TOC) $(MATH_FORMULAS) $(CSS_ARGS) $(METADATA_ARGS) $(FILTER_ARGS) $(DEBUG_ARGS) +PANDOC_COMMAND = pandoc + +# Per-format options + +EPUB_ARGS = --epub-cover-image=$(COVER_IMAGE) +HTML_ARGS = --standalone --to=html5 PDF_ARGS = -V geometry:margin=1in -V documentclass=report --pdf-engine=xelatex #################################################################################################### @@ -42,17 +54,17 @@ pdf: $(BUILD)/pdf/$(OUTPUT_FILENAME).pdf $(BUILD)/epub/$(OUTPUT_FILENAME).epub: $(MAKEFILE) $(METADATA) $(CHAPTERS) $(CSS_FILE) $(IMAGES) \ $(COVER_IMAGE) mkdir -p $(BUILD)/epub - pandoc $(ARGS) --epub-cover-image=$(COVER_IMAGE) -o $@ $(CHAPTERS) + $(PANDOC_COMMAND) $(ARGS) $(EPUB_ARGS) -o $@ $(CHAPTERS) @echo "$@ was built" $(BUILD)/html/$(OUTPUT_FILENAME).html: $(MAKEFILE) $(METADATA) $(CHAPTERS) $(CSS_FILE) $(IMAGES) mkdir -p $(BUILD)/html - pandoc $(ARGS) --standalone --to=html5 -o $@ $(CHAPTERS) + $(PANDOC_COMMAND) $(ARGS) $(HTML_ARGS) -o $@ $(CHAPTERS) cp -R $(IMAGES_FOLDER)/ $(BUILD)/html/$(IMAGES_FOLDER)/ cp $(CSS_FILE) $(BUILD)/html/$(CSS_FILE) @echo "$@ was built" $(BUILD)/pdf/$(OUTPUT_FILENAME).pdf: $(MAKEFILE) $(METADATA) $(CHAPTERS) $(CSS_FILE) $(IMAGES) mkdir -p $(BUILD)/pdf - pandoc $(ARGS) $(PDF_ARGS) -o $@ $(CHAPTERS) + $(PANDOC_COMMAND) $(ARGS) $(PDF_ARGS) -o $@ $(CHAPTERS) @echo "$@ was built" diff --git a/README.md b/README.md index d69b0ae..b99a157 100644 --- a/README.md +++ b/README.md @@ -174,22 +174,15 @@ 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). +Pandoc will automatically convert the image into a figure, using the title (the text between the +brackets) as a caption. -If you want to resize the image, you may use this syntax, available in Pandoc 1.16: +If you want to resize the image, you may use this syntax, available since Pandoc 1.16: ```md ![A cool seagull.](images/seagull.png){ width=50% height=50% } ``` -Also, to reference an image, use LaTeX labels: - -```md -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: ` syntax to add a caption: @@ -204,20 +197,6 @@ Use markdown table, and use the `Table: ` syntax to add Table: This is an example table. ``` -If you want to reference a table, use LaTeX labels: - -```md -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: @@ -236,6 +215,62 @@ $$\mu = \sum_{i=0}^{N} \frac{x_i}{N}$$ [Here](https://www.codecogs.com/latex/eqneditor.php)'s an online equation editor. +#### Cross references + +Originally, this template used LaTeX labels for auto numbering on images, tables, equations or +sections, like this: + +```md +Please, admire the gloriousnes of Figure \ref{seagull_image}. + +![A cool seagull.\label{seagull_image}](images/seagull.png) +``` + +**However, these references only works when exporting to a LaTeX-based format (i.e. PDF, LaTeX).** + +In case you need cross references support on other formats, this template now support cross +references using [Pandoc filters](https://pandoc.org/filters.html). If you want to use them, use a +valid plugin and with its own syntax. + +Using [pandoc-crossref](https://github.com/lierdakil/pandoc-crossref) is highly recommended, but +there are other alternatives which use a similar syntax, like +[pandoc-xnos](https://github.com/tomduck/pandoc-xnos). + +First, enable the filter on the *Makefile* by updating the `FILTER_ARGS` variable with your new +filter(s): + +```make +FILTER_ARGS = --filter pandoc-crossref +``` + +Then, you may use the filter cross references. For example, *pandoc-crossref* uses +`{#:}` for definitions and `@:id` for referencing. Some examples: + +```md +List of references: + +- Check @fig:seagull. +- Check @tbl:table. +- Check @eq:equation. + +List of elements to reference: + +![A cool seagull](images/seagull.png){#fig:seagull} + +$$ y = mx + b $$ {#eq:equation} + +| Index | Name | +| ----- | ---- | +| 0 | AAA | +| 1 | BBB | +| ... | ... | + +Table: This is an example table. {#tbl:table} +``` + +Check the desired filter settings and usage for more information +([pandoc-crossref usage](http://lierdakil.github.io/pandoc-crossref/)). + ### Output This template uses *Makefile* to automatize the building process. Instead of using the *pandoc cli @@ -281,7 +316,7 @@ The generated file(s) will be placed in *build/html*. If you want to configure the output, you'll probably have to look the [Pandoc Manual](http://pandoc.org/MANUAL.html) for further information about pdf (LaTeX) generation, -custom styles, etc. +custom styles, etc, and modify the Makefile file accordingly. ## References diff --git a/chapters/01-introduction.md b/chapters/01-introduction.md index 5d4f1f3..ee79247 100644 --- a/chapters/01-introduction.md +++ b/chapters/01-introduction.md @@ -2,14 +2,17 @@ This is the first paragraph of the introduction chapter. -## First +## First: Images -This is the first subsection. Please, admire the gloriousnes of Figure \ref{seagull_image}. +This is the first subsection. Please, admire the gloriousnes of this seagull: +![A cool seagull.](images/seagull.png) -![A cool seagull.\label{seagull_image}](images/seagull.png) +A bigger seagull: -## Second +![A cool big seagull.](images/seagull.png){ width=320px } + +## Second: Tables This is the second subsection. @@ -18,17 +21,15 @@ Please, check [First] subsection. Please, check [this](#first) subsection. -Please, check Table \ref{example_table}. - | Index | Name | | ----- | ---- | | 0 | AAA | | 1 | BBB | | ... | ... | -Table: This is an example table.\label{example_table} +Table: This is an example table. -## Third +## Third: Equations Formula example: $\mu = \sum_{i=0}^{N} \frac{x_i}{N}$ @@ -47,3 +48,27 @@ hello_world ``` Check these unicode characters: ǽߢð€đŋμ + +## Fourth: Cross references + +These cross references are disabled by default. To enable them, check the +_[Cross references](https://github.com/wikiti/pandoc-book-template#cross-references)_ +section on the README.md file. + +Here's a list of cross references: + +- Check @fig:seagull. +- Check @tbl:table. +- Check @eq:equation. + +![A cool seagull](images/seagull.png){#fig:seagull} + +$$ y = mx + b $$ {#eq:equation} + +| Index | Name | +| ----- | ---- | +| 0 | AAA | +| 1 | BBB | +| ... | ... | + +Table: This is an example table. {#tbl:table} diff --git a/metadata.yml b/metadata.yml index 34fa75f..673a354 100644 --- a/metadata.yml +++ b/metadata.yml @@ -2,9 +2,13 @@ title: My book title author: Daniel Herzog rights: MIT License -language: en-US -tags: [book, my-book, etc] +lang: en-US +tags: [pandoc, book, my-book, etc] abstract: | Your summary. mainfont: DejaVu Sans + +# Filter preferences: +# - pandoc-crossref +linkReferences: true ---