added custom Markdown template for intermediate transformations and f…

…or Pandoc Markdown to Pandoc Markdown conversions--this prevents includes from being included prematurely and makes roundtrip conversions behave as expected (#20)

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## v0.5.0 (dev)
 
+* "Includes" are now skipped during internal, intermediate file
+  transformations, which prevents duplicated "includes" and associated errors
+  (#20).  This applies to `header-includes`, `include-before`,
+  `include-after`, `--include-in-header`, `--include-before-body`, and
+  `--include-after-body`.  Roundtrip conversion from Pandoc Markdown to Pandoc
+  Markdown now skips all "includes" and also ignores `toc`/`table-of-contents`
+  and `--toc`/`--table-of-contents`.  This allows Codebraid to be used as a
+  preprocessor and saves YAML metadata settings for a subsequent conversion
+  from Pandoc Markdown to another format.
 * Added option `jupyter_timeout` for the first code chunk in a session (#30).
 * Fixed Pandoc 2.8+ compatibility by using `-raw_attribute` in intermediate
   Markdown.  Code output in raw format (interpreted as Markdown) is no longer

README.md

@@ -172,12 +172,31 @@ Manual installation:  `python3 setup.py install` or `python setup.py install`
 ## Converting a document
 
 Simply run `codebraid pandoc <normal pandoc options>`.  Note that
-`--overwrite` is required for existing files.
+`--overwrite` is required to overwrite existing files.  If you are using a
+defaults file, `--from`, `--to`, and `--output` must be given explicitly and
+cannot be inherited from the defaults file.  If you are using a defaults file
+and converting to a standalone Pandoc Markdown document, `--standalone` should
+be given explicitly rather than being inherited from the defaults file.
 
 `codebraid` should typically be run in the same directory as the document, so
 that the default working directory for code is the document directory.  Future
 releases will allow customization of the working directory.
 
+If you are converting from Pandoc Markdown to Pandoc Markdown with
+`--standalone` (basically using `codebraid` to preprocess Markdown documents),
+note that the following YAML metadata fields and command-line options are
+ignored in that situation:
+  * `header-includes` and `--include-in-header`
+  * `include-before` and `--include-before-body`
+  * `include-after` and `--include-after-body`
+  * `toc`/`table-of-contents` and `--toc`/`--table-of-contents`
+
+This is typically what you want.  Usually, "include" and a table of contents
+are desired in a final output format like HTML or PDF, not in a Pandoc
+Markdown file.  In the rare cases where "includes" and a table of contents are
+needed in Markdown documents, this can be accomplished by piping the output of
+`codebraid` through `pandoc`.
+
 
 ## Caching
 

codebraid/converters/pandoc.py

@@ -18,6 +18,7 @@
 import subprocess
 import sys
 import tempfile
+import textwrap
 from typing import Dict, List, Optional, Sequence, Union
 import warnings
 from .base import CodeChunk, Converter, Include
@@ -577,6 +578,25 @@ def __init__(self, *,
         elif float(pandoc_version_match.group()) < 2.4:
             raise RuntimeError('Pandoc at "{0}" is version {1}, but >= 2.4 is required'.format(pandoc_path, float(pandoc_version_match.group())))
         self.pandoc_path = pandoc_path
+        if platform.system() == 'Windows':
+            pandoc_template_path = pathlib.Path('~/AppData/Roaming/pandoc/templates').expanduser()
+        else:
+            pandoc_data_path = pathlib.Path(os.environ.get('XDG_DATA_HOME', '~/.local/share')).expanduser() / 'pandoc'
+            if not pandoc_data_path.is_dir():
+                pandoc_data_path = pathlib.Path('~/.pandoc').expanduser()
+            pandoc_template_path = pandoc_data_path / 'templates'
+        if not pandoc_template_path.is_dir():
+            pandoc_template_path.mkdir(parents=True)
+        codebraid_markdown_roundtrip_template_path = pandoc_template_path / 'codebraid_pandoc_markdown_roundtrip.md'
+        if not codebraid_markdown_roundtrip_template_path.is_file():
+            codebraid_markdown_roundtrip_template_path.write_text(textwrap.dedent('''\
+                $if(titleblock)$
+                $titleblock$
+
+                $endif$
+                $body$
+                '''), encoding='utf8')
+        self.codebraid_markdown_roundtrip_template_path = codebraid_markdown_roundtrip_template_path
 
         if not isinstance(pandoc_file_scope, bool):
             raise TypeError
@@ -675,6 +695,11 @@ def _run_pandoc(self, *,
             cmd_list.extend(['--to', to_format + to_format_pandoc_extensions])
         if standalone:
             cmd_list.append('--standalone')
+            if to_format is None:
+                if output_path is not None and output_path.suffix in ('.md', '.markdown'):
+                    cmd_list.extend(['--template', self.codebraid_markdown_roundtrip_template_path.as_posix()])
+            elif to_format == 'markdown':
+                cmd_list.extend(['--template', self.codebraid_markdown_roundtrip_template_path.as_posix()])
         if trace:
             cmd_list.append('--trace')
         if file_scope:

codebraid/version.py

@@ -1,4 +1,4 @@
 # -*- coding: utf-8 -*-
 
 from .fmtversion import get_version_plus_info
-__version__, __version_info__ = get_version_plus_info(0, 5, 0, 'dev', 6)
+__version__, __version_info__ = get_version_plus_info(0, 5, 0, 'dev', 7)