Github automatically parses anchor tags out of your headers. So you can do the following:
[Custom foo description](#foo)
# Foo
In the above case, the Foo
header has generated an anchor tag with the name foo
Note: just one #
for all heading sizes, no space between #
and anchor name, anchor tag names must be lowercase, and delimited by dashes if multi-word.
[click on this link](#my-multi-word-header)
### My Multi Word Header
Update
Works out of the box with pandoc
too.
I believe that all the previously proposed solutions (apart from those that require specific implementations) result in the comments being included in the output HTML, even if they are not displayed.
If you want a comment that is strictly for yourself (readers of the converted document should not be able to see it, even with "view source") you could (ab)use the link labels (for use with reference style links) that are available in the core Markdown specification:
http://daringfireball.net/projects/markdown/syntax#link
That is:
[comment]: <> (This is a comment, it will not be included)
[comment]: <> (in the output file unless you use it in)
[comment]: <> (a reference style link.)
Or you could go further:
[//]: <> (This is also a comment.)
To improve platform compatibility (and to save one keystroke) it is also possible to use #
(which is a legitimate hyperlink target) instead of <>
:
[//]: # (This may be the most platform independent comment)
For maximum portability it is important to insert a blank line before and after this type of comments, because some Markdown parsers do not work correctly when definitions brush up against regular text. The most recent research with Babelmark shows that blank lines before and after are both important. Some parsers will output the comment if there is no blank line before, and some parsers will exclude the following line if there is no blank line after.
In general, this approach should work with most Markdown parsers, since it's part of the core specification. (even if the behavior when multiple links are defined, or when a link is defined but never used, is not strictly specified).
Best Answer
You can keep the simplicity of using the RStudio
Knit
button and reproducibility of a YAML header by using the undocumentedknit
hook to redefine what the button does (default function called isrmarkdown::render
). Theoutput_file
parameter of the render function specifies the file name, so by setting it you override the standard behaviour of using the same prefix as the input filename.e.g. to always output a file called myfile.pdf
The function can be an anonymous one-liner as well as imported from a package, as seen here with slidify.
You can set your own YAML headers (I don't know if this is generally advised anyway), accessible under
rmarkdown::metadata$newheader
but they don't seem available from within this sort of function as far as I can see.As for passing file name in from an R chunk... if you're referring to code chunks below the YAML header, from my experience I don't think that's possible(?). Headers can contain inline R commands (single backtick-enclosed, starting with
r
), but seemingly not for this hook function.Related:
output_file