Merge pull request #9 from wikiti/bugs/cross-refs

Add cross-references support

Makefile

@@ -2,20 +2,40 @@
 # 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)
+
+# Debugging
+
+# DEBUG_ARGS = --verbose
+
+# Pandoc filtes - uncomment the following variable to enable cross references filter. For more
+# information, check the "Cross references" section on the README.md file.
+
+# FILTER_ARGS = --filter pandoc-crossref
+
+# Combined arguments
+
+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 +62,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"

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: <Your table description>` syntax to add a caption:
@@ -204,20 +197,6 @@ Use markdown table, and use the `Table: <Your table description>` 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
+`{#<type>:<id>}` for definitions and `@<type>: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
 

chapters/01-introduction.md

@@ -2,23 +2,24 @@
 
 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.
 
 
-Please, check [First] subsection.
+Please, check [First: Images] subsection.
 
-Please, check [this](#first) subsection.
-
-Please, check Table \ref{example_table}.
+Please, check [this](#first-images) subsection.
 
 | Index | Name |
 | ----- | ---- |
@@ -26,9 +27,9 @@ Please, check Table \ref{example_table}.
 | 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}

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
 ---