Hybrid workflows
initial copy-pasta from https://github.com/DigitalPublishingToolkit/Hybrid-Publishing-Resources/wiki/From-Manuscript-to-EPUB:
The conversion from a manuscript to EPUB it is a step by step process, that consists of:
- .docx - Manuscript - .docx - editing the manuscript according to the INC style guide
- Markdown - Source - converting the manuscript files to Markdown files.
- ICML files for inDesign - converting the individual Markdown source into ICML files that can be imported into inDesign
- EPUB Output -converting the compound Markdown source file to an EPUB
Note: The section "6.3. Do-it-yourself EPUB using Pandoc" form From Print to Ebooks is an important complement to this tutorial and set of tools
Work Environment
To produce EPUB will rely on environment made up of elements * an empty directory for each project * shell - the command line interpreter * git - the distributed versioning system * makefile - a file that functions as recipe books, where each recipe gathers its resources and process them to produce the expected outcome. * Pandoc - the swiss-army-knife of document conversions * Calibre - EPUB viewer and editor * Plain text editor (see Masterclass for more information on this software)
0. Folder structure
To create folder structure, which will be understood by the scripts from this repository, you need to run:
./scripts/create_folders.sh
This script will generate the following folder structure, which you'll use to store the files essentially for the creation of the EPUB.
├── docx ├── epub ├── icml ├── md │ └── imgs └── scripts
1. Manuscript: .docx
This is a preparatory stage. Yet it is highly important for the series of conversions that will lead to the different publication's outputs.
Ensure that the docx filenames: * are numbered, starting from 01, 02, ... according to their order * have no spaces, commas, or dots, except for the file extension * include only ASCII characters, no Ã,À,õ, etc..
You'll be editing the text document handed by the author - the manuscript -, according to INC styleguide: section "Document Formatting/Layout", subsection "General".
Do pay special attention to this part of the INC styleguide. Following it rigorously will ensure that your manuscripts will convert flawlessly to markdown (the next step).
2. Source: converting the manuscript files to Markdown files
Run: make markdowns to start this stage.
This command will convert all the .docx files inside the docx/folder into corresponding markdown files inside md/ folder.
The resulting markdown files are meant as source files, from which all of the publication's outputs will be generated.
The reason for using markdown as a the source format comes from easiness by which they can be read and written, they high compatibility with other markup languages (HTML, ICML) and the corresponding outputs (EPUB/Website, inDesign Project)
2.1 Metadata in Markdown
Each of the resulting markdown files contain a metadata header. You can fill those fields with the corresponding information.
Note on metadata: You can change the metadata fields and values that are added to each article, by editing the template file used to generate the markdown files: essay.md.template
2.2 Images in Markdown
At this stage you should insert the images in to the essay, now in markdown format.
First of all, you need to save all the images included in the essays in the folder md/imgs/ Then place the images on the markdown files: 
Don't forget to include captions, if the image has them. Markdown captions will become visible, and associated to the image in the EPUB output
3 ICML files for inDesign
Run: make icmls to start this stage.
The individual Markdown source files, stored in md/, can be converted into ICML files which can be imported into inDesign.
ICML files are useful, since they ensure that the structural information of the Markdown source files is also present in the inDesign projects, which use them.
Another point in favor of ICML is the possibility of updating the content and structure of the inDesign projects, by updating the Markdown source files, converting the once more to ICML. For this to happens is however necessary that inDesign remains linked to its source, and that the designers works with paragraph and chapter styles, instead of directly into the text.
Note: malformatted links in the markdown files will create problems when imported into inDesign.
4. Outputs
4.1 EPUB Output
book.epub
Run: make epub to start this stage.
Essential files:
To produce an EPUB a few resources (files) are needed, namely the cover image, metadata, stylesheet, and fonts.
This files will strongly influence the EPUB's outcome, and consequently should be edited for each publication or series of publication
epub/metadata.xml- EPUB metadataepub/styles.epub.css- EPUB css style-sheet MUST BE EDITEDepub/cover.jpg- EPUB cover MUST BE CHANGED
Optional fonts:
- lib/ - folder for storing custom fonts, that will be used in the EPUB
Note on the use of custom fonts: If you choose to use fonts, make sure to change the makefile to include the use of fonts in the makefile epub rule, such as in the rule bellow, where --epub-embed-font=lib/UbuntuMono-B.ttf \ was added to allow for the use of the Ubuntu Mono font. Also include the font on th EPUB style-sheet with @font-face rule
4.2 EPUB check
The health of the created EPUB can be checked with http://validator.idpf.org/
4.3 EPUB edit
Once it has been created the EPUB can be change manually by using Calibre's recent tool Edit Book
Folder structure
├── compound │ ├── article.body.template.md │ ├── article.head.template.md │ └── TOC.md ├── docs │ ├── 01_01_Introduction.md │ ├── 01_02_Colophone.md │ ├── 01_Intro.md │ ├── 02_01_article.md │ ├── 02_02_article.md │ ├── 02_Content.md │ └── images ├── epub │ ├── cover.png │ ├── metadata.xml │ └── styles.epub.css ├── gitignore ├── guides │ ├── Styleguide_INC_2014.md │ └── Template_INC_essay.md ├── images │ └── chucky.jpg ├── lib │ └── UbuntuMono-B.ttf ├── makefile ├── README.md ├── scripts │ ├── chapter.sh │ └── expand_toc.py