diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -29,7 +29,7 @@ ------------- A less than perfect conversion does not necessarily mean there's -a bug in pandoc. Quoting from the README: +a bug in pandoc. Quoting from the MANUAL: > Because Pandoc's intermediate representation of a document is less > expressive than many of the formats it converts between, one should @@ -124,7 +124,7 @@ below under [Tests](#tests).) If you are adding a new writer or reader, you must include tests. -7. If you are adding a new feature, include updates to the README. +7. If you are adding a new feature, include updates to MANUAL.txt. 8. All code must be released under the general license governing pandoc (GPL v2). @@ -132,7 +132,7 @@ 9. It is better not to introduce new dependencies. Dependencies on external C libraries should especially be avoided. -10. We aim for compatibility with ghc versions from 7.4.2 to the +10. We aim for compatibility with ghc versions from 7.8.3 to the latest release. All pull requests and commits are tested automatically on travis-ci.org, using GHC versions in the `Tested-With` stanza of `pandoc.cabal`. We currently relax @@ -152,7 +152,7 @@ or, if you're using [stack], - stack init + stack setup stack test The test program is `tests/test-pandoc.hs`. @@ -259,7 +259,7 @@ - `Text.Pandoc.Shared` is a grab-bag of shared utility functions. - `Text.Pandoc.Writers.Shared` contains utilities used in writers only. - `Text.Pandoc.Slides` contains functions for splitting a markdown document - into slides, using the conventions described in the README. + into slides, using the conventions described in the MANUAL. - `Text.Pandoc.Templates` defines pandoc's templating system. - `Text.Pandoc.UTF8` contains functions for converting text to and from UTF8 bytestrings (strict and lazy). @@ -270,7 +270,7 @@ [pandoc-discuss]: http://groups.google.com/group/pandoc-discuss [issue tracker]: https://github.com/jgm/pandoc/issues -[User's Guide]: http://pandoc.org/README.html +[User's Guide]: http://pandoc.org/MANUAL.html [FAQs]: http://pandoc.org/faqs.html [EditorConfig]: http://editorconfig.org/ [Haskell platform]: http://www.haskell.org/platform/ diff --git a/COPYING b/COPYING deleted file mode 100644 --- a/COPYING +++ /dev/null @@ -1,346 +0,0 @@ -GNU GENERAL PUBLIC LICENSE -========================== - -Version 2, June 1991 - -Copyright (C) 1989, 1991 Free Software Foundation, Inc. -51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA - -Everyone is permitted to copy and distribute verbatim copies -of this license document, but changing it is not allowed. - -Preamble --------- - -The licenses for most software are designed to take away your -freedom to share and change it. By contrast, the GNU General Public -License is intended to guarantee your freedom to share and change free -software--to make sure the software is free for all its users. This -General Public License applies to most of the Free Software -Foundation's software and to any other program whose authors commit to -using it. (Some other Free Software Foundation software is covered by -the GNU Library General Public License instead.) You can apply it to -your programs, too. - -When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -this service if you wish), that you receive source code or can get it -if you want it, that you can change the software or use pieces of it -in new free programs; and that you know you can do these things. - -To protect your rights, we need to make restrictions that forbid -anyone to deny you these rights or to ask you to surrender the rights. -These restrictions translate to certain responsibilities for you if you -distribute copies of the software, or if you modify it. - -For example, if you distribute copies of such a program, whether -gratis or for a fee, you must give the recipients all the rights that -you have. You must make sure that they, too, receive or can get the -source code. And you must show them these terms so they know their -rights. - -We protect your rights with two steps: (1) copyright the software, and -(2) offer you this license which gives you legal permission to copy, -distribute and/or modify the software. - -Also, for each author's protection and ours, we want to make certain -that everyone understands that there is no warranty for this free -software. If the software is modified by someone else and passed on, we -want its recipients to know that what they have is not the original, so -that any problems introduced by others will not reflect on the original -authors' reputations. - -Finally, any free program is threatened constantly by software -patents. We wish to avoid the danger that redistributors of a free -program will individually obtain patent licenses, in effect making the -program proprietary. To prevent this, we have made it clear that any -patent must be licensed for everyone's free use or not licensed at all. - -The precise terms and conditions for copying, distribution and -modification follow. - -GNU GENERAL PUBLIC LICENSE --------------------------- - -TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION - -0. This License applies to any program or other work which contains - a notice placed by the copyright holder saying it may be distributed - under the terms of this General Public License. The "Program", below, - refers to any such program or work, and a "work based on the Program" - means either the Program or any derivative work under copyright law: - that is to say, a work containing the Program or a portion of it, - either verbatim or with modifications and/or translated into another - language. (Hereinafter, translation is included without limitation in - the term "modification".) Each licensee is addressed as "you". - - Activities other than copying, distribution and modification are not - covered by this License; they are outside its scope. The act of - running the Program is not restricted, and the output from the Program - is covered only if its contents constitute a work based on the - Program (independent of having been made by running the Program). - Whether that is true depends on what the Program does. - -1. You may copy and distribute verbatim copies of the Program's - source code as you receive it, in any medium, provided that you - conspicuously and appropriately publish on each copy an appropriate - copyright notice and disclaimer of warranty; keep intact all the - notices that refer to this License and to the absence of any warranty; - and give any other recipients of the Program a copy of this License - along with the Program. - - You may charge a fee for the physical act of transferring a copy, and - you may at your option offer warranty protection in exchange for a fee. - -2. You may modify your copy or copies of the Program or any portion - of it, thus forming a work based on the Program, and copy and - distribute such modifications or work under the terms of Section 1 - above, provided that you also meet all of these conditions: - - a) You must cause the modified files to carry prominent notices - stating that you changed the files and the date of any change. - - b) You must cause any work that you distribute or publish, that in - whole or in part contains or is derived from the Program or any - part thereof, to be licensed as a whole at no charge to all third - parties under the terms of this License. - - c) If the modified program normally reads commands interactively - when run, you must cause it, when started running for such - interactive use in the most ordinary way, to print or display an - announcement including an appropriate copyright notice and a - notice that there is no warranty (or else, saying that you provide - a warranty) and that users may redistribute the program under - these conditions, and telling the user how to view a copy of this - License. (Exception: if the Program itself is interactive but - does not normally print such an announcement, your work based on - the Program is not required to print an announcement.) - - These requirements apply to the modified work as a whole. If - identifiable sections of that work are not derived from the Program, - and can be reasonably considered independent and separate works in - themselves, then this License, and its terms, do not apply to those - sections when you distribute them as separate works. But when you - distribute the same sections as part of a whole which is a work based - on the Program, the distribution of the whole must be on the terms of - this License, whose permissions for other licensees extend to the - entire whole, and thus to each and every part regardless of who wrote it. - - Thus, it is not the intent of this section to claim rights or contest - your rights to work written entirely by you; rather, the intent is to - exercise the right to control the distribution of derivative or - collective works based on the Program. - - In addition, mere aggregation of another work not based on the Program - with the Program (or with a work based on the Program) on a volume of - a storage or distribution medium does not bring the other work under - the scope of this License. - -3. You may copy and distribute the Program (or a work based on it, - under Section 2) in object code or executable form under the terms of - Sections 1 and 2 above provided that you also do one of the following: - - a) Accompany it with the complete corresponding machine-readable - source code, which must be distributed under the terms of Sections - 1 and 2 above on a medium customarily used for software interchange; or, - - b) Accompany it with a written offer, valid for at least three - years, to give any third party, for a charge no more than your - cost of physically performing source distribution, a complete - machine-readable copy of the corresponding source code, to be - distributed under the terms of Sections 1 and 2 above on a medium - customarily used for software interchange; or, - - c) Accompany it with the information you received as to the offer - to distribute corresponding source code. (This alternative is - allowed only for noncommercial distribution and only if you - received the program in object code or executable form with such - an offer, in accord with Subsection b above.) - - The source code for a work means the preferred form of the work for - making modifications to it. For an executable work, complete source - code means all the source code for all modules it contains, plus any - associated interface definition files, plus the scripts used to - control compilation and installation of the executable. However, as a - special exception, the source code distributed need not include - anything that is normally distributed (in either source or binary - form) with the major components (compiler, kernel, and so on) of the - operating system on which the executable runs, unless that component - itself accompanies the executable. - - If distribution of executable or object code is made by offering - access to copy from a designated place, then offering equivalent - access to copy the source code from the same place counts as - distribution of the source code, even though third parties are not - compelled to copy the source along with the object code. - -4. You may not copy, modify, sublicense, or distribute the Program - except as expressly provided under this License. Any attempt - otherwise to copy, modify, sublicense or distribute the Program is - void, and will automatically terminate your rights under this License. - However, parties who have received copies, or rights, from you under - this License will not have their licenses terminated so long as such - parties remain in full compliance. - -5. You are not required to accept this License, since you have not - signed it. However, nothing else grants you permission to modify or - distribute the Program or its derivative works. These actions are - prohibited by law if you do not accept this License. Therefore, by - modifying or distributing the Program (or any work based on the - Program), you indicate your acceptance of this License to do so, and - all its terms and conditions for copying, distributing or modifying - the Program or works based on it. - -6. Each time you redistribute the Program (or any work based on the - Program), the recipient automatically receives a license from the - original licensor to copy, distribute or modify the Program subject to - these terms and conditions. You may not impose any further - restrictions on the recipients' exercise of the rights granted herein. - You are not responsible for enforcing compliance by third parties to - this License. - -7. If, as a consequence of a court judgment or allegation of patent - infringement or for any other reason (not limited to patent issues), - conditions are imposed on you (whether by court order, agreement or - otherwise) that contradict the conditions of this License, they do not - excuse you from the conditions of this License. If you cannot - distribute so as to satisfy simultaneously your obligations under this - License and any other pertinent obligations, then as a consequence you - may not distribute the Program at all. For example, if a patent - license would not permit royalty-free redistribution of the Program by - all those who receive copies directly or indirectly through you, then - the only way you could satisfy both it and this License would be to - refrain entirely from distribution of the Program. - - If any portion of this section is held invalid or unenforceable under - any particular circumstance, the balance of the section is intended to - apply and the section as a whole is intended to apply in other - circumstances. - - It is not the purpose of this section to induce you to infringe any - patents or other property right claims or to contest validity of any - such claims; this section has the sole purpose of protecting the - integrity of the free software distribution system, which is - implemented by public license practices. Many people have made - generous contributions to the wide range of software distributed - through that system in reliance on consistent application of that - system; it is up to the author/donor to decide if he or she is willing - to distribute software through any other system and a licensee cannot - impose that choice. - - This section is intended to make thoroughly clear what is believed to - be a consequence of the rest of this License. - -8. If the distribution and/or use of the Program is restricted in - certain countries either by patents or by copyrighted interfaces, the - original copyright holder who places the Program under this License - may add an explicit geographical distribution limitation excluding - those countries, so that distribution is permitted only in or among - countries not thus excluded. In such case, this License incorporates - the limitation as if written in the body of this License. - -9. The Free Software Foundation may publish revised and/or new versions - of the General Public License from time to time. Such new versions will - be similar in spirit to the present version, but may differ in detail to - address new problems or concerns. - - Each version is given a distinguishing version number. If the Program - specifies a version number of this License which applies to it and "any - later version", you have the option of following the terms and conditions - either of that version or of any later version published by the Free - Software Foundation. If the Program does not specify a version number of - this License, you may choose any version ever published by the Free Software - Foundation. - -10. If you wish to incorporate parts of the Program into other free - programs whose distribution conditions are different, write to the author - to ask for permission. For software which is copyrighted by the Free - Software Foundation, write to the Free Software Foundation; we sometimes - make exceptions for this. Our decision will be guided by the two goals - of preserving the free status of all derivatives of our free software and - of promoting the sharing and reuse of software generally. - -NO WARRANTY - -11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY - FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN - OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES - PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED - OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF - MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS - TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE - PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, - REPAIR OR CORRECTION. - -12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING - WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR - REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, - INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING - OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED - TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY - YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER - PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE - POSSIBILITY OF SUCH DAMAGES. - -END OF TERMS AND CONDITIONS - -How to Apply These Terms to Your New Programs ---------------------------------------------- - -If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these terms. - -To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -convey the exclusion of warranty; and each file should have at least -the "copyright" line and a pointer to where the full notice is found. - - - Copyright (C) - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA - -Also add information on how to contact you by electronic and paper mail. - -If the program is interactive, make it output a short notice like this -when it starts in an interactive mode: - - Gnomovision version 69, Copyright (C) year name of author - Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. - This is free software, and you are welcome to redistribute it - under certain conditions; type `show c' for details. - -The hypothetical commands `show w' and `show c' should show the appropriate -parts of the General Public License. Of course, the commands you use may -be called something other than `show w' and `show c'; they could even be -mouse-clicks or menu items--whatever suits your program. - -You should also get your employer (if you work as a programmer) or your -school, if any, to sign a "copyright disclaimer" for the program, if -necessary. Here is a sample; alter the names: - - Yoyodyne, Inc., hereby disclaims all copyright interest in the program - `Gnomovision' (which makes passes at compilers) written by James Hacker. - - , 1 April 1989 - Ty Coon, President of Vice - -This General Public License does not permit incorporating your program into -proprietary programs. If your program is a subroutine library, you may -consider it more useful to permit linking proprietary applications with the -library. If this is what you want to do, use the GNU Library General -Public License instead of this License. diff --git a/COPYING.md b/COPYING.md new file mode 100644 --- /dev/null +++ b/COPYING.md @@ -0,0 +1,361 @@ +### GNU GENERAL PUBLIC LICENSE + +Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc. + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + +### Preamble + +The licenses for most software are designed to take away your freedom +to share and change it. By contrast, the GNU General Public License is +intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Lesser General Public License instead.) You can apply it to +your programs, too. + +When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + +To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if +you distribute copies of the software, or if you modify it. + +For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + +We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + +Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, +we want its recipients to know that what they have is not the +original, so that any problems introduced by others will not reflect +on the original authors' reputations. + +Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at +all. + +The precise terms and conditions for copying, distribution and +modification follow. + +### TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + +**0.** This License applies to any program or other work which +contains a notice placed by the copyright holder saying it may be +distributed under the terms of this General Public License. The +"Program", below, refers to any such program or work, and a "work +based on the Program" means either the Program or any derivative work +under copyright law: that is to say, a work containing the Program or +a portion of it, either verbatim or with modifications and/or +translated into another language. (Hereinafter, translation is +included without limitation in the term "modification".) Each licensee +is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the Program +(independent of having been made by running the Program). Whether that +is true depends on what the Program does. + +**1.** You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a +fee. + +**2.** You may modify your copy or copies of the Program or any +portion of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + +**a)** You must cause the modified files to carry prominent notices +stating that you changed the files and the date of any change. + + +**b)** You must cause any work that you distribute or publish, that in +whole or in part contains or is derived from the Program or any part +thereof, to be licensed as a whole at no charge to all third parties +under the terms of this License. + + +**c)** If the modified program normally reads commands interactively +when run, you must cause it, when started running for such interactive +use in the most ordinary way, to print or display an announcement +including an appropriate copyright notice and a notice that there is +no warranty (or else, saying that you provide a warranty) and that +users may redistribute the program under these conditions, and telling +the user how to view a copy of this License. (Exception: if the +Program itself is interactive but does not normally print such an +announcement, your work based on the Program is not required to print +an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote +it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + +**3.** You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + +**a)** Accompany it with the complete corresponding machine-readable +source code, which must be distributed under the terms of Sections 1 +and 2 above on a medium customarily used for software interchange; or, + + +**b)** Accompany it with a written offer, valid for at least three +years, to give any third party, for a charge no more than your cost of +physically performing source distribution, a complete machine-readable +copy of the corresponding source code, to be distributed under the +terms of Sections 1 and 2 above on a medium customarily used for +software interchange; or, + + +**c)** Accompany it with the information you received as to the offer +to distribute corresponding source code. (This alternative is allowed +only for noncommercial distribution and only if you received the +program in object code or executable form with such an offer, in +accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + +**4.** You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt otherwise +to copy, modify, sublicense or distribute the Program is void, and +will automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + +**5.** You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + +**6.** Each time you redistribute the Program (or any work based on +the Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + +**7.** If, as a consequence of a court judgment or allegation of +patent infringement or for any other reason (not limited to patent +issues), conditions are imposed on you (whether by court order, +agreement or otherwise) that contradict the conditions of this +License, they do not excuse you from the conditions of this License. +If you cannot distribute so as to satisfy simultaneously your +obligations under this License and any other pertinent obligations, +then as a consequence you may not distribute the Program at all. For +example, if a patent license would not permit royalty-free +redistribution of the Program by all those who receive copies directly +or indirectly through you, then the only way you could satisfy both it +and this License would be to refrain entirely from distribution of the +Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + +**8.** If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + +**9.** The Free Software Foundation may publish revised and/or new +versions of the General Public License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and +"any later version", you have the option of following the terms and +conditions either of that version or of any later version published by +the Free Software Foundation. If the Program does not specify a +version number of this License, you may choose any version ever +published by the Free Software Foundation. + +**10.** If you wish to incorporate parts of the Program into other +free programs whose distribution conditions are different, write to +the author to ask for permission. For software which is copyrighted by +the Free Software Foundation, write to the Free Software Foundation; +we sometimes make exceptions for this. Our decision will be guided by +the two goals of preserving the free status of all derivatives of our +free software and of promoting the sharing and reuse of software +generally. + +**NO WARRANTY** + +**11.** BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO +WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. +EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR +OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY +KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE +PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME +THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + +**12.** IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN +WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY +AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU +FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR +CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE +PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING +RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A +FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF +SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH +DAMAGES. + +### END OF TERMS AND CONDITIONS + +### How to Apply These Terms to Your New Programs + +If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these +terms. + +To do so, attach the following notices to the program. It is safest to +attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + one line to give the program's name and an idea of what it does. + Copyright (C) yyyy name of author + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation; either version 2 + of the License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + +Also add information on how to contact you by electronic and paper +mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) year name of author + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details + type `show w'. This is free software, and you are welcome + to redistribute it under certain conditions; type `show c' + for details. + +The hypothetical commands \`show w' and \`show c' should show the +appropriate parts of the General Public License. Of course, the +commands you use may be called something other than \`show w' and +\`show c'; they could even be mouse-clicks or menu items--whatever +suits your program. + +You should also get your employer (if you work as a programmer) or +your school, if any, to sign a "copyright disclaimer" for the program, +if necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright + interest in the program `Gnomovision' + (which makes passes at compilers) written + by James Hacker. + + signature of Ty Coon, 1 April 1989 + Ty Coon, President of Vice + +This General Public License does not permit incorporating your program +into proprietary programs. If your program is a subroutine library, +you may consider it more useful to permit linking proprietary +applications with the library. If this is what you want to do, use the +[GNU Lesser General Public +License](http://www.gnu.org/licenses/lgpl.html) instead of this +License. diff --git a/COPYRIGHT b/COPYRIGHT --- a/COPYRIGHT +++ b/COPYRIGHT @@ -17,7 +17,7 @@ along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA -The GNU General Public License is available in the file COPYING in +The GNU General Public License is available in the file COPYING.md in the source distribution. On Debian systems, the complete text of the GPL can be found in `/usr/share/common-licenses/GPL`. diff --git a/INSTALL b/INSTALL deleted file mode 100644 --- a/INSTALL +++ /dev/null @@ -1,234 +0,0 @@ -% Installing pandoc - -These instructions explain how to install pandoc from source. -Binary packages or ports of pandoc are available for freebsd -and several linux distributions, so check your package manager. -There are also binary installers for Windows and Mac OS X. - -If you are installing the development version from github, see also: -https://github.com/jgm/pandoc/wiki/Installing-the-development-version-of-pandoc - -Quick install with stack ------------------------- - -1. Install [stack](http://docs.haskellstack.org/en/stable/install_and_upgrade.html). - -2. If you used git to get the pandoc source (as opposed to unpacking - a release tarball), do - - git submodule update --init - -3. In the pandoc source directory, - - stack install - - You may be prompted to run `stack setup`, which will automatically - download the ghc compiler if needed. - - -Quick install with cabal ------------------------- - -1. Install the [Haskell platform]. This will give you [GHC] and - the [cabal-install] build tool. - -2. Update your package database: - - cabal update - -3. Use `cabal` to install pandoc and its dependencies: - - cabal install pandoc - - This procedure will install the released version of pandoc, - which will be downloaded automatically from HackageDB. - - If this step fails, and you are using an older version - of the Haskell Platform, e.g. on Debian stable, you may need to - upgrade your version of cabal: - - cabal install cabal-install - ~/.cabal/bin/cabal update - ~/.cabal/bin/cabal install pandoc - - If you want to install a modified or development version - of pandoc instead, switch to the source directory and do - as above, but without the 'pandoc': - - cabal install - - Note: If you obtained the source from the git repository (rather - than a release tarball), you'll need to do - - git submodule update --init - - to fetch the contents of `data/templates` before `cabal install`. - -4. Make sure the `$CABALDIR/bin` directory is in your path. You should - now be able to run `pandoc`: - - pandoc --help - - [Not sure where `$CABALDIR` is?](http://www.haskell.org/haskellwiki/Cabal-Install#The_cabal-install_configuration_file) - -5. If you want to process citations with pandoc, you will also need to - install a separate package, `pandoc-citeproc`. This can be installed - using cabal: - - cabal install pandoc-citeproc - - By default `pandoc-citeproc` uses the "i;unicode-casemap" method - to sort bibliography entries (RFC 5051). If you would like to - use the locale-sensitive unicode collation algorithm instead, - specify the `unicode_collation` flag: - - cabal install pandoc-citeproc -funicode_collation - - Note that this requires the `text-icu` library, which in turn - depends on the C library `icu4c`. Installation directions - vary by platform. Here is how it might work on OSX with homebrew: - - brew install icu4c - cabal install --extra-lib-dirs=/usr/local/Cellar/icu4c/51.1/lib \ - --extra-include-dirs=/usr/local/Cellar/icu4c/51.1/include \ - -funicode_collation text-icu pandoc-citeproc - -The `pandoc.1` man page will be installed automatically. cabal shows -you where it is installed: you may need to set your `MANPATH` -accordingly. If `README` has been modified, the man page can be -rebuilt: `make man/pandoc.1`. - -The `pandoc-citeproc.1` man page will also be installed automatically. - -[GHC]: http://www.haskell.org/ghc/ -[Haskell platform]: http://hackage.haskell.org/platform/ -[cabal-install]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall - -Custom install --------------- - -This is a step-by-step procedure that offers maximal control -over the build and installation. Most users should use the -quick install, but this information may be of use to packagers. -For more details, see the [Cabal User's Guide]. These instructions -assume that the pandoc source directory is your working directory. - -1. Install dependencies: in addition to the [Haskell platform], - you will need a number of additional libraries. You can install - them all with - - cabal update - cabal install --only-dependencies - -2. Configure: - - cabal configure --prefix=DIR --bindir=DIR --libdir=DIR \ - --datadir=DIR --libsubdir=DIR --datasubdir=DIR --docdir=DIR \ - --htmldir=DIR --program-prefix=PREFIX --program-suffix=SUFFIX \ - --mandir=DIR --flags=FLAGSPEC - - All of the options have sensible defaults that can be overridden - as needed. - - `FLAGSPEC` is a list of Cabal configuration flags, optionally - preceded by a `-` (to force the flag to `false`), and separated - by spaces. Pandoc's flags include: - - - `embed_data_files`: embed all data files into the binary (default no). - This is helpful if you want to create a relocatable binary. - Note: if this option is selected, you need to install the - `hsb2hs` preprocessor: `cabal install hsb2hs` (version 0.3.1 or - higher is required). - - - `https`: enable support for downloading resources over https - (using the `http-client` and `http-client-tls` libraries). - -3. Build: - - cabal build - -4. Build API documentation: - - cabal haddock --html-location=URL --hyperlink-source - -5. Copy the files: - - cabal copy --destdir=PATH - - The default destdir is `/`. - -6. Register pandoc as a GHC package: - - cabal register - - Package managers may want to use the `--gen-script` option to - generate a script that can be run to register the package at - install time. - -Creating a relocatable binary ------------------------------ - -It is possible to compile pandoc such that the data files -pandoc uses are embedded in the binary. The resulting binary -can be run from any directory and is completely self-contained. - - cabal install hsb2hs # a required build tool - cabal install --flags="embed_data_files" citeproc-hs - cabal configure --flags="embed_data_files" - cabal build - -You can find the pandoc executable in `dist/build/pandoc`. Copy this wherever -you please. - -Or alternatively with `stack`: - - stack install pandoc --flag pandoc:embed_data_files - -[zip-archive]: http://hackage.haskell.org/package/zip-archive -[highlighting-kate]: http://hackage.haskell.org/package/highlighting-kate -[blaze-html]: http://hackage.haskell.org/package/blaze-html -[Cabal User's Guide]: http://www.haskell.org/cabal/release/latest/doc/users-guide/builders.html#setup-configure-paths - -Running tests -------------- - -Pandoc comes with an automated test suite integrated to cabal. -To build the tests: - - cabal configure --enable-tests && cabal build - -To run the tests: - - cabal test - -To run particular tests (pattern-matching on their names), use -the `-t` option: - - cabal test --test-options='-t markdown' - -If you add a new feature to pandoc, please add tests as well, following -the pattern of the existing tests. The test suite code is in -`tests/test-pandoc.hs`. If you are adding a new reader or writer, it is -probably easiest to add some data files to the `tests` directory, and -modify `tests/Tests/Old.hs`. Otherwise, it is better to modify the module -under the `tests/Tests` hierarchy corresponding to the pandoc module you -are changing. - -Running benchmarks ------------------- - -To build the benchmarks: - - cabal configure --enable-benchmarks && cabal build - -To run the benchmarks: - - cabal bench - -To use a smaller sample size so the benchmarks run faster: - - cabal bench --benchmark-options='-s 20' - -To run just the markdown benchmarks: - - cabal bench --benchmark-options='markdown' diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,339 @@ +# Installing pandoc + +## Windows + + - There is a package installer at pandoc's [download page]. + + - For PDF output, you'll also need to install LaTeX. + We recommend [MiKTeX](http://miktex.org/). + +## Mac OS X + + - There is a package installer at pandoc's [download page]. + If you later want to uninstall the package, you can do so + by downloading [this script][uninstaller] + and running it with `perl uninstall-pandoc.pl`. + + - You can also install pandoc using + [homebrew](http://brew.sh): `brew install pandoc`. + + - For PDF output, you'll also need LaTeX. Because a full [MacTeX] + installation takes more than a gigabyte of disk space, we recommend + installing [BasicTeX](http://www.tug.org/mactex/morepackages.html) + (64M) and using the `tlmgr` tool to install additional packages + as needed. If you get errors warning of fonts not found, try + + tlmgr install collection-fontsrecommended + +## Linux + + - First, try your package manager. + Pandoc is in the [Debian], [Ubuntu], [Slackware], + [Arch], [Fedora], [NiXOS], [openSUSE], and [gentoo] repositories. + Note, however, that versions in the repositories are often + old. + + - For 64-bit [Debian] and [Ubuntu], we provide a debian package + on the [download page]. + + sudo dpkg -i $DEB + + where `$DEB` is the path to the downloaded deb, will + will install the `pandoc` and `pandoc-citeproc` executables + and man pages. If you use an RPM-based distro, you may be + able to install this deb using `alien`, or try + + ar p $DEB data.tar.gz | sudo tar xvz --strip-components 2 -C /usr/local + + - If you'd rather install pandoc in your home directory, say + in `$HOME/.local`, then you can extract the files manually + from the deb: + + ar p $DEB data.tar.gz | tar xvz --strip-components 2 -C $HOME/.local/ + + where, again, `$DEB` is the path to the downloaded deb. + + - If the version in your repository is too old and you cannot + use the deb we provide, you can install from source, using the + instructions below under [Installing from source]. + Note that most distros have the Haskell platform in their + package repositories. For example, on Debian/Ubuntu, + you can install it with `apt-get install haskell-platform`. + + - For PDF output, you'll need LaTeX. We recommend installing + [TeX Live](http://www.tug.org/texlive/) via your package + manager. (On Debian/Ubuntu, `apt-get install texlive`.) + +## BSD + + - Pandoc is in the [NetBSD] and [FreeBSD ports] repositories. + +## Compiling from source + +If for some reason a binary package is not available for your +platform, or if you want to hack on pandoc or use a non-released +version, you can install from source. + +### Getting the pandoc source code + +Source tarballs can be found at +. For example, to +fetch the source for version 1.17.0.3: + + wget https://hackage.haskell.org/package/pandoc-1.17.0.3/pandoc-1.17.0.3.tar.gz + tar xvzf pandoc-1.17.0.3.tar.gz + cd pandoc-1.17.0.3 + +Or you can fetch the development code by cloning the repository: + + git clone https://github.com/jgm/pandoc + cd pandoc + git submodule update --init # to fetch the templates + +Note: there may be times when the development code is broken +or depends on other libraries which must be installed +separately. Unless you really know what you're doing, install +the last released version. + +### Quick stack method + +The easiest way to build pandoc from source is to use [stack]: + +1. Install [stack]. + +2. Change to the pandoc source directory and issue the following commands: + + stack setup + stack install --test + + `stack setup` will automatically download the ghc compiler + if you don't have it. `stack install` will install the + `pandoc` executable into `~/.local/bin`, which you should + add to your `PATH`. This process will take a while, and + will consume a considerable amount of disk space. + +### Quick cabal method + +1. Install the [Haskell platform]. This will give you [GHC] and + the [cabal-install] build tool. Note that pandoc requires + GHC >= 7.8. + +2. Update your package database: + + cabal update + +3. Use `cabal` to install pandoc and its dependencies: + + cabal install pandoc --enable-tests + + This procedure will install the released version of pandoc, + which will be downloaded automatically from HackageDB. + + If you want to install a modified or development version + of pandoc instead, switch to the source directory and do + as above, but without the 'pandoc': + + cabal install + + Note: If you obtained the source from the git repository (rather + than a release tarball), you'll need to do + + git submodule update --init + + to fetch the contents of `data/templates` before `cabal install`. + +4. Make sure the `$CABALDIR/bin` directory is in your path. You should + now be able to run `pandoc`: + + pandoc --help + + [Not sure where `$CABALDIR` is?](http://www.haskell.org/haskellwiki/Cabal-Install#The_cabal-install_configuration_file) + +5. If you want to process citations with pandoc, you will also need to + install a separate package, `pandoc-citeproc`. This can be installed + using cabal: + + cabal install pandoc-citeproc + + By default `pandoc-citeproc` uses the "i;unicode-casemap" method + to sort bibliography entries (RFC 5051). If you would like to + use the locale-sensitive unicode collation algorithm instead, + specify the `unicode_collation` flag: + + cabal install pandoc-citeproc -funicode_collation + + Note that this requires the `text-icu` library, which in turn + depends on the C library `icu4c`. Installation directions + vary by platform. Here is how it might work on OSX with homebrew: + + brew install icu4c + cabal install --extra-lib-dirs=/usr/local/Cellar/icu4c/51.1/lib \ + --extra-include-dirs=/usr/local/Cellar/icu4c/51.1/include \ + -funicode_collation text-icu pandoc-citeproc + +6. The `pandoc.1` man page will be installed automatically. cabal shows + you where it is installed: you may need to set your `MANPATH` + accordingly. If `MANUAL.txt` has been modified, the man page can be + rebuilt: `make man/pandoc.1`. + + The `pandoc-citeproc.1` man page will also be installed automatically. + + +### Custom cabal method + +This is a step-by-step procedure that offers maximal control +over the build and installation. Most users should use the +quick install, but this information may be of use to packagers. +For more details, see the [Cabal User's Guide]. These instructions +assume that the pandoc source directory is your working directory. + +1. Install dependencies: in addition to the [Haskell platform], + you will need a number of additional libraries. You can install + them all with + + cabal update + cabal install --only-dependencies + +2. Configure: + + cabal configure --prefix=DIR --bindir=DIR --libdir=DIR \ + --datadir=DIR --libsubdir=DIR --datasubdir=DIR --docdir=DIR \ + --htmldir=DIR --program-prefix=PREFIX --program-suffix=SUFFIX \ + --mandir=DIR --flags=FLAGSPEC --enable-tests + + All of the options have sensible defaults that can be overridden + as needed. + + `FLAGSPEC` is a list of Cabal configuration flags, optionally + preceded by a `-` (to force the flag to `false`), and separated + by spaces. Pandoc's flags include: + + - `embed_data_files`: embed all data files into the binary (default no). + This is helpful if you want to create a relocatable binary. + Note: if this option is selected, you need to install the + `hsb2hs` preprocessor: `cabal install hsb2hs` (version 0.3.1 or + higher is required). + + - `https`: enable support for downloading resources over https + (using the `http-client` and `http-client-tls` libraries). + +3. Build: + + cabal build + cabal test + +4. Build API documentation: + + cabal haddock --html-location=URL --hyperlink-source + +5. Copy the files: + + cabal copy --destdir=PATH + + The default destdir is `/`. + +6. Register pandoc as a GHC package: + + cabal register + + Package managers may want to use the `--gen-script` option to + generate a script that can be run to register the package at + install time. + +### Creating a relocatable binary + +It is possible to compile pandoc such that the data files +pandoc uses are embedded in the binary. The resulting binary +can be run from any directory and is completely self-contained. +With cabal, add `-fembed_data_files` to the `cabal configure` +or `cabal install` commands. + +With stack, use `--flag pandoc:embed_data_files`. + + + +### Running tests + +Pandoc comes with an automated test suite. +To run with cabal, `cabal test`; to run with stack, `stack +test`. + +To run particular tests (pattern-matching on their names), use +the `-t` option: + + cabal test --test-options='-t markdown' + +If you add a new feature to pandoc, please add tests as well, following +the pattern of the existing tests. The test suite code is in +`tests/test-pandoc.hs`. If you are adding a new reader or writer, it is +probably easiest to add some data files to the `tests` directory, and +modify `tests/Tests/Old.hs`. Otherwise, it is better to modify the module +under the `tests/Tests` hierarchy corresponding to the pandoc module you +are changing. + +### Running benchmarks + +To build and run the benchmarks: + + cabal configure --enable-benchmarks && cabal build + cabal bench + +or with stack: + + stack bench + +To use a smaller sample size so the benchmarks run faster: + + cabal bench --benchmark-options='-s 20' + +To run just the markdown benchmarks: + + cabal bench --benchmark-options='markdown' + +### Building the whole pandoc ecosystem + +Sometimes pandoc's development code depends on unreleased versions +of dependent libraries. You'll need to build these as well. A +maximal build method would be + + mkdir pandoc-build + cd pandoc-build + git clone https://github.com/jgm/pandoc-types + git clone https://github.com/jgm/texmath + git clone https://github.com/jgm/pandoc-citeproc + git clone https://github.com/jgm/pandoc + git clone https://github.com/jgm/cmark-hs + git clone https://github.com/jgm/zip-archive + cd pandoc + git submodule update --init + stack install --test --install-ghc --stack-yaml stack.full.yaml + +To pull in the latest changes, after you've done this and there have been +changes in the repositories: Visit each repository in pandoc-build +(pandoc-types, texmath, pandoc-citeproc, pandoc, zip-archive, cmark-hs) and do +`git pull`. In the pandoc repo, also do `git submodule update` and `stack +install --test --stack-yaml stack.full.yaml`. + + +[Arch]: https://www.archlinux.org/packages/community/x86_64/pandoc/ +[Cabal User's Guide]: http://www.haskell.org/cabal/release/latest/doc/users-guide/builders.html#setup-configure-paths +[Debian]: http://packages.debian.org/lenny/pandoc +[Fedora]: https://apps.fedoraproject.org/packages/pandoc +[FreeBSD ports]: http://www.freshports.org/textproc/pandoc/ +[GHC]: http://www.haskell.org/ghc/ +[GPL]: http://www.gnu.org/copyleft/gpl.html +[Haskell platform]: http://hackage.haskell.org/platform/ +[MacPorts]: http://trac.macports.org/browser/trunk/dports/textproc/pandoc/Portfile +[MacTeX]: https://tug.org/mactex/ +[NetBSD]: http://pkgsrc.se/wip/pandoc +[NixOS]: http://nixos.org/nixos/ +[Slackware]: http://www.linuxpackages.net/search_view.php?by=name&name=pandoc&ver= +[Ubuntu]: http://www.ubuntu.com +[download page]: https://github.com/jgm/pandoc/releases/latest +[gentoo]: http://packages.gentoo.org/package/app-text/pandoc +[haskell repository]: https://wiki.archlinux.org/index.php/Haskell_Package_Guidelines#.5Bhaskell.5D +[openSUSE]: https://software.opensuse.org/package/pandoc +[source tarball]: http://hackage.haskell.org/package/pandoc +[stack]: http://docs.haskellstack.org/en/stable/install_and_upgrade.html +[cabal-install]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall +[uninstaller]: https://raw.githubusercontent.com/jgm/pandoc/master/osx/uninstall-pandoc.pl diff --git a/MANUAL.txt b/MANUAL.txt new file mode 100644 --- /dev/null +++ b/MANUAL.txt @@ -0,0 +1,4164 @@ +% Pandoc User's Guide +% John MacFarlane +% October 26, 2016 + +Synopsis +======== + +`pandoc` [*options*] [*input-file*]... + +Description +=========== + +Pandoc is a [Haskell] library for converting from one markup format to +another, and a command-line tool that uses this library. It can read +[Markdown], [CommonMark], [PHP Markdown Extra], [GitHub-Flavored Markdown], +[MultiMarkdown], and (subsets of) [Textile], [reStructuredText], [HTML], +[LaTeX], [MediaWiki markup], [TWiki markup], [Haddock markup], [OPML], [Emacs +Org mode], [DocBook], [txt2tags], [EPUB], [ODT] and [Word docx]; and it can +write plain text, [Markdown], [CommonMark], [PHP Markdown Extra], +[GitHub-Flavored Markdown], [MultiMarkdown], [reStructuredText], [XHTML], +[HTML5], [LaTeX] \(including [`beamer`] slide shows\), [ConTeXt], [RTF], [OPML], +[DocBook], [OpenDocument], [ODT], [Word docx], [GNU Texinfo], [MediaWiki +markup], [DokuWiki markup], [ZimWiki markup], [Haddock markup], +[EPUB] \(v2 or v3\), [FictionBook2], [Textile], [groff man] pages, +[Emacs Org mode], [AsciiDoc], [InDesign ICML], [TEI Simple], and [Slidy], +[Slideous], [DZSlides], [reveal.js] or [S5] HTML slide shows. It can also +produce [PDF] output on systems where LaTeX, ConTeXt, or `wkhtmltopdf` is +installed. + +Pandoc's enhanced version of Markdown includes syntax for [footnotes], +[tables], flexible [ordered lists], [definition lists], [fenced code blocks], +[superscripts and subscripts], [strikeout], [metadata blocks], automatic tables of +contents, embedded LaTeX [math], [citations], and [Markdown inside HTML block +elements][Extension: `markdown_in_html_blocks`]. (These enhancements, described +further under [Pandoc's Markdown], can be disabled using the +`markdown_strict` input or output format.) + +In contrast to most existing tools for converting Markdown to HTML, which +use regex substitutions, pandoc has a modular design: it consists of a +set of readers, which parse text in a given format and produce a native +representation of the document, and a set of writers, which convert +this native representation into a target format. Thus, adding an input +or output format requires only adding a reader or writer. + +Because pandoc's intermediate representation of a document is less +expressive than many of the formats it converts between, one should +not expect perfect conversions between every format and every other. +Pandoc attempts to preserve the structural elements of a document, but +not formatting details such as margin size. And some document elements, +such as complex tables, may not fit into pandoc's simple document +model. While conversions from pandoc's Markdown to all formats aspire +to be perfect, conversions from formats more expressive than pandoc's +Markdown can be expected to be lossy. + +[Markdown]: http://daringfireball.net/projects/markdown/ +[CommonMark]: http://commonmark.org +[PHP Markdown Extra]: https://michelf.ca/projects/php-markdown/extra/ +[GitHub-Flavored Markdown]: https://help.github.com/articles/github-flavored-markdown/ +[MultiMarkdown]: http://fletcherpenney.net/multimarkdown/ +[reStructuredText]: http://docutils.sourceforge.net/docs/ref/rst/introduction.html +[S5]: http://meyerweb.com/eric/tools/s5/ +[Slidy]: http://www.w3.org/Talks/Tools/Slidy/ +[Slideous]: http://goessner.net/articles/slideous/ +[HTML]: http://www.w3.org/html/ +[HTML5]: http://www.w3.org/TR/html5/ +[XHTML]: http://www.w3.org/TR/xhtml1/ +[LaTeX]: http://latex-project.org +[`beamer`]: https://ctan.org/pkg/beamer +[Beamer User's Guide]: http://ctan.math.utah.edu/ctan/tex-archive/macros/latex/contrib/beamer/doc/beameruserguide.pdf +[ConTeXt]: http://contextgarden.net/ +[RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format +[DocBook]: http://docbook.org +[txt2tags]: http://txt2tags.org +[EPUB]: http://idpf.org/epub +[OPML]: http://dev.opml.org/spec2.html +[OpenDocument]: http://opendocument.xml.org +[ODT]: http://en.wikipedia.org/wiki/OpenDocument +[Textile]: http://redcloth.org/textile +[MediaWiki markup]: https://www.mediawiki.org/wiki/Help:Formatting +[DokuWiki markup]: https://www.dokuwiki.org/dokuwiki +[ZimWiki markup]: http://zim-wiki.org/manual/Help/Wiki_Syntax.html +[TWiki markup]: http://twiki.org/cgi-bin/view/TWiki/TextFormattingRules +[Haddock markup]: https://www.haskell.org/haddock/doc/html/ch03s08.html +[groff man]: http://developer.apple.com/DOCUMENTATION/Darwin/Reference/ManPages/man7/groff_man.7.html +[Haskell]: https://www.haskell.org +[GNU Texinfo]: http://www.gnu.org/software/texinfo/ +[Emacs Org mode]: http://orgmode.org +[AsciiDoc]: http://www.methods.co.nz/asciidoc/ +[DZSlides]: http://paulrouget.com/dzslides/ +[Word docx]: http://www.microsoft.com/interop/openup/openxml/default.aspx +[PDF]: https://www.adobe.com/pdf/ +[reveal.js]: http://lab.hakim.se/reveal-js/ +[FictionBook2]: http://www.fictionbook.org/index.php/Eng:XML_Schema_Fictionbook_2.1 +[InDesign ICML]: https://www.adobe.com/content/dam/Adobe/en/devnet/indesign/cs55-docs/IDML/idml-specification.pdf +[TEI Simple]: https://github.com/TEIC/TEI-Simple + +Using `pandoc` +-------------- + +If no *input-file* is specified, input is read from *stdin*. +Otherwise, the *input-files* are concatenated (with a blank +line between each) and used as input. Output goes to *stdout* by +default (though output to *stdout* is disabled for the `odt`, `docx`, +`epub`, and `epub3` output formats). For output to a file, use the +`-o` option: + + pandoc -o output.html input.txt + +By default, pandoc produces a document fragment, not a standalone +document with a proper header and footer. To produce a standalone +document, use the `-s` or `--standalone` flag: + + pandoc -s -o output.html input.txt + +For more information on how standalone documents are produced, see +[Templates], below. + +Instead of a file, an absolute URI may be given. In this case +pandoc will fetch the content using HTTP: + + pandoc -f html -t markdown http://www.fsf.org + +If multiple input files are given, `pandoc` will concatenate them all (with +blank lines between them) before parsing. This feature is disabled for + binary input formats such as `EPUB`, `odt`, and `docx`. + +The format of the input and output can be specified explicitly using +command-line options. The input format can be specified using the +`-r/--read` or `-f/--from` options, the output format using the +`-w/--write` or `-t/--to` options. Thus, to convert `hello.txt` from +Markdown to LaTeX, you could type: + + pandoc -f markdown -t latex hello.txt + +To convert `hello.html` from HTML to Markdown: + + pandoc -f html -t markdown hello.html + +Supported output formats are listed below under the `-t/--to` option. +Supported input formats are listed below under the `-f/--from` option. Note +that the `rst`, `textile`, `latex`, and `html` readers are not complete; +there are some constructs that they do not parse. + +If the input or output format is not specified explicitly, `pandoc` +will attempt to guess it from the extensions of +the input and output filenames. Thus, for example, + + pandoc -o hello.tex hello.txt + +will convert `hello.txt` from Markdown to LaTeX. If no output file +is specified (so that output goes to *stdout*), or if the output file's +extension is unknown, the output format will default to HTML. +If no input file is specified (so that input comes from *stdin*), or +if the input files' extensions are unknown, the input format will +be assumed to be Markdown unless explicitly specified. + +Pandoc uses the UTF-8 character encoding for both input and output. +If your local character encoding is not UTF-8, you +should pipe input and output through [`iconv`]: + + iconv -t utf-8 input.txt | pandoc | iconv -f utf-8 + +Note that in some output formats (such as HTML, LaTeX, ConTeXt, +RTF, OPML, DocBook, and Texinfo), information about +the character encoding is included in the document header, which +will only be included if you use the `-s/--standalone` option. + +[`iconv`]: http://www.gnu.org/software/libiconv/ + +Creating a PDF +-------------- + +To produce a PDF, specify an output file with a `.pdf` extension. +By default, pandoc will use LaTeX to convert it to PDF: + + pandoc test.txt -o test.pdf + +Production of a PDF requires that a LaTeX engine be installed (see +`--latex-engine`, below), and assumes that the following LaTeX packages +are available: [`amsfonts`], [`amsmath`], [`lm`], +[`ifxetex`], [`ifluatex`], [`eurosym`], [`listings`] (if the +`--listings` option is used), [`fancyvrb`], [`longtable`], +[`booktabs`], [`graphicx`] and [`grffile`] (if the +document contains images), [`hyperref`], [`ulem`], +[`geometry`] (with the `geometry` variable set), [`setspace`] (with +`linestretch`), and [`babel`] (with `lang`). The use of `xelatex` or +`lualatex` as the LaTeX engine requires [`fontspec`]; `xelatex` uses +[`mathspec`], [`polyglossia`] (with `lang`), [`xecjk`], and +[`bidi`] (with the `dir` variable set). The [`upquote`] and +[`microtype`] packages are used if available, and [`csquotes`] will +be used for [smart punctuation] if added to the template or included in +any header file. The [`natbib`], [`biblatex`], [`bibtex`], and [`biber`] +packages can optionally be used for [citation rendering]. These are +included with all recent versions of [TeX Live]. + +Alternatively, pandoc can use ConTeXt or `wkhtmltopdf` to create a PDF. +To do this, specify an output file with a `.pdf` extension, +as before, but add `-t context` or `-t html5` to the command line. + +PDF output can be controlled using [variables for LaTeX] (if +LaTeX is used) and [variables for ConTeXt] (if ConTeXt is used). +If `wkhtmltopdf` is used, then the variables `margin-left`, +`margin-right`, `margin-top`, `margin-bottom`, and `papersize` +will affect the output, as will `--css`. + +[`amsfonts`]: https://ctan.org/pkg/amsfonts +[`amsmath`]: https://ctan.org/pkg/amsmath +[`lm`]: https://ctan.org/pkg/lm +[`ifxetex`]: https://ctan.org/pkg/ifxetex +[`ifluatex`]: https://ctan.org/pkg/ifluatex +[`eurosym`]: https://ctan.org/pkg/eurosym +[`listings`]: https://ctan.org/pkg/listings +[`fancyvrb`]: https://ctan.org/pkg/fancyvrb +[`longtable`]: https://ctan.org/pkg/longtable +[`booktabs`]: https://ctan.org/pkg/booktabs +[`graphicx`]: https://ctan.org/pkg/graphicx +[`grffile`]: https://ctan.org/pkg/grffile +[`geometry`]: https://ctan.org/pkg/geometry +[`setspace`]: https://ctan.org/pkg/setspace +[`xecjk`]: https://ctan.org/pkg/xecjk +[`hyperref`]: https://ctan.org/pkg/hyperref +[`ulem`]: https://ctan.org/pkg/ulem +[`babel`]: https://ctan.org/pkg/babel +[`bidi`]: https://ctan.org/pkg/bidi +[`mathspec`]: https://ctan.org/pkg/mathspec +[`polyglossia`]: https://ctan.org/pkg/polyglossia +[`fontspec`]: https://ctan.org/pkg/fontspec +[`upquote`]: https://ctan.org/pkg/upquote +[`microtype`]: https://ctan.org/pkg/microtype +[`csquotes`]: https://ctan.org/pkg/csquotes +[`natbib`]: https://ctan.org/pkg/natbib +[`biblatex`]: https://ctan.org/pkg/biblatex +[`bibtex`]: https://ctan.org/pkg/bibtex +[`biber`]: https://ctan.org/pkg/biber +[TeX Live]: http://www.tug.org/texlive/ + +Options +======= + +General options +--------------- + +`-f` *FORMAT*, `-r` *FORMAT*, `--from=`*FORMAT*, `--read=`*FORMAT* + +: Specify input format. *FORMAT* can be `native` (native Haskell), + `json` (JSON version of native AST), `markdown` (pandoc's + extended Markdown), `markdown_strict` (original unextended + Markdown), `markdown_phpextra` (PHP Markdown Extra), `markdown_github` + (GitHub-Flavored Markdown), `markdown_mmd` (MultiMarkdown), + `commonmark` (CommonMark Markdown), `textile` (Textile), `rst` + (reStructuredText), `html` (HTML), `docbook` (DocBook), `t2t` + (txt2tags), `docx` (docx), `odt` (ODT), `epub` (EPUB), `opml` (OPML), + `org` (Emacs Org mode), `mediawiki` (MediaWiki markup), `twiki` (TWiki + markup), `haddock` (Haddock markup), or `latex` (LaTeX). If + `+lhs` is appended to `markdown`, `rst`, `latex`, or `html`, the + input will be treated as literate Haskell source: see [Literate + Haskell support], below. Markdown + syntax extensions can be individually enabled or disabled by + appending `+EXTENSION` or `-EXTENSION` to the format name. So, for + example, `markdown_strict+footnotes+definition_lists` is strict + Markdown with footnotes and definition lists enabled, and + `markdown-pipe_tables+hard_line_breaks` is pandoc's Markdown + without pipe tables and with hard line breaks. See [Pandoc's + Markdown], below, for a list of extensions and + their names. See `--list-input-formats` and `--list-extensions`, + below. + +`-t` *FORMAT*, `-w` *FORMAT*, `--to=`*FORMAT*, `--write=`*FORMAT* + +: Specify output format. *FORMAT* can be `native` (native Haskell), + `json` (JSON version of native AST), `plain` (plain text), + `markdown` (pandoc's extended Markdown), `markdown_strict` + (original unextended Markdown), `markdown_phpextra` (PHP Markdown + Extra), `markdown_github` (GitHub-Flavored Markdown), `markdown_mmd` + (MultiMarkdown), `commonmark` (CommonMark Markdown), `rst` + (reStructuredText), `html` (XHTML), `html5` (HTML5), `latex` + (LaTeX), `beamer` (LaTeX beamer slide show), `context` (ConTeXt), + `man` (groff man), `mediawiki` (MediaWiki markup), + `dokuwiki` (DokuWiki markup), `zimwiki` (ZimWiki markup), + `textile` (Textile), `org` (Emacs Org mode), + `texinfo` (GNU Texinfo), `opml` (OPML), `docbook` (DocBook 4), + `docbook5` (DocBook 5), `opendocument` (OpenDocument), `odt` + (OpenOffice text document), `docx` (Word docx), `haddock` + (Haddock markup), `rtf` (rich text format), `epub` (EPUB v2 + book), `epub3` (EPUB v3), `fb2` (FictionBook2 e-book), + `asciidoc` (AsciiDoc), `icml` (InDesign ICML), `tei` (TEI + Simple), `slidy` (Slidy HTML and javascript slide show), + `slideous` (Slideous HTML and javascript slide show), + `dzslides` (DZSlides HTML5 + javascript slide show), + `revealjs` (reveal.js HTML5 + javascript slide show), `s5` + (S5 HTML and javascript slide show), or the path of a custom + lua writer (see [Custom writers], below). Note that `odt`, + `epub`, and `epub3` output will not be directed to *stdout*; + an output filename must be specified using the `-o/--output` + option. If `+lhs` is appended to `markdown`, `rst`, `latex`, + `beamer`, `html`, or `html5`, the output will be rendered as + literate Haskell source: see [Literate Haskell support], + below. Markdown syntax extensions can be individually + enabled or disabled by appending `+EXTENSION` or + `-EXTENSION` to the format name, as described above under `-f`. + See `--list-output-formats` and `--list-extensions`, below. + +`-o` *FILE*, `--output=`*FILE* + +: Write output to *FILE* instead of *stdout*. If *FILE* is + `-`, output will go to *stdout*. (Exception: if the output + format is `odt`, `docx`, `epub`, or `epub3`, output to stdout is disabled.) + +`--data-dir=`*DIRECTORY* + +: Specify the user data directory to search for pandoc data files. + If this option is not specified, the default user data directory + will be used. This is, in Unix: + + $HOME/.pandoc + + in Windows XP: + + C:\Documents And Settings\USERNAME\Application Data\pandoc + + and in Windows Vista or later: + + C:\Users\USERNAME\AppData\Roaming\pandoc + + You can find the default user data directory on your system by + looking at the output of `pandoc --version`. + A `reference.odt`, `reference.docx`, `epub.css`, `templates`, + `slidy`, `slideous`, or `s5` directory + placed in this directory will override pandoc's normal defaults. + +`--bash-completion` + +: Generate a bash completion script. To enable bash completion + with pandoc, add this to your `.bashrc`: + + eval "$(pandoc --bash-completion)" + +`--verbose` + +: Give verbose debugging output. Currently this only has an effect + with PDF output. + +`--list-input-formats` + +: List supported input formats, one per line. + +`--list-output-formats` + +: List supported output formats, one per line. + +`--list-extensions` + +: List supported Markdown extensions, one per line, followed + by a `+` or `-` indicating whether it is enabled by default + in pandoc's Markdown. + +`--list-highlight-languages` + +: List supported languages for syntax highlighting, one per + line. + +`--list-highlight-styles` + +: List supported styles for syntax highlighting, one per line. + See `--highlight-style`. + +`-v`, `--version` + +: Print version. + +`-h`, `--help` + +: Show usage message. + +Reader options +-------------- + +`-R`, `--parse-raw` + +: Parse untranslatable HTML codes and LaTeX environments as raw HTML + or LaTeX, instead of ignoring them. Affects only HTML and LaTeX + input. Raw HTML can be printed in Markdown, reStructuredText, Emacs Org + mode, HTML, Slidy, Slideous, DZSlides, reveal.js, and S5 output; raw LaTeX + can be printed in Markdown, reStructuredText, Emacs Org mode, LaTeX, and + ConTeXt output. The default is for the readers to omit untranslatable + HTML codes and LaTeX environments. (The LaTeX reader does pass through + untranslatable LaTeX *commands*, even if `-R` is not specified.) + +`-S`, `--smart` + +: Produce typographically correct output, converting straight quotes + to curly quotes, `---` to em-dashes, `--` to en-dashes, and + `...` to ellipses. Nonbreaking spaces are inserted after certain + abbreviations, such as "Mr." (Note: This option is selected automatically + when the output format is `latex` or `context`, unless `--no-tex-ligatures` + is used. It has no effect for `latex` input.) + +`--old-dashes` + +: Selects the pandoc <= 1.8.2.1 behavior for parsing smart dashes: `-` before + a numeral is an en-dash, and `--` is an em-dash. This option is selected + automatically for `textile` input. + +`--base-header-level=`*NUMBER* + +: Specify the base level for headers (defaults to 1). + +`--indented-code-classes=`*CLASSES* + +: Specify classes to use for indented code blocks--for example, + `perl,numberLines` or `haskell`. Multiple classes may be separated + by spaces or commas. + +`--default-image-extension=`*EXTENSION* + +: Specify a default extension to use when image paths/URLs have no + extension. This allows you to use the same source for formats that + require different kinds of images. Currently this option only affects + the Markdown and LaTeX readers. + +`--file-scope` + +: Parse each file individually before combining for multifile + documents. This will allow footnotes in different files with the + same identifiers to work as expected. If this option is set, + footnotes and links will not work across files. Reading binary + files (docx, odt, epub) implies `--file-scope`. + +`--filter=`*EXECUTABLE* + +: Specify an executable to be used as a filter transforming the + pandoc AST after the input is parsed and before the output is + written. The executable should read JSON from stdin and write + JSON to stdout. The JSON must be formatted like pandoc's own + JSON input and output. The name of the output format will be + passed to the filter as the first argument. Hence, + + pandoc --filter ./caps.py -t latex + + is equivalent to + + pandoc -t json | ./caps.py latex | pandoc -f json -t latex + + The latter form may be useful for debugging filters. + + Filters may be written in any language. `Text.Pandoc.JSON` + exports `toJSONFilter` to facilitate writing filters in Haskell. + Those who would prefer to write filters in python can use the + module [`pandocfilters`], installable from PyPI. There are also + pandoc filter libraries in [PHP], [perl], and + [javascript/node.js]. + + If no directory is provided pandoc will look for executable or + non-executable filters in the director `$DATADIR/filters`, and + then for executable filters in the user's `PATH`. If you want to + run a script in the working directory, preface the filename with + `./`. + + In order of preference, pandoc will look for filters in + + 1. a specified full or relative path (executable or + non-executable) + + 2. `$DATADIR/filters` (executable or non-executable) + + 3. `$PATH` (executable only) + +`-M` *KEY*[`=`*VAL*], `--metadata=`*KEY*[`:`*VAL*] + +: Set the metadata field *KEY* to the value *VAL*. A value specified + on the command line overrides a value specified in the document. + Values will be parsed as YAML boolean or string values. If no value is + specified, the value will be treated as Boolean true. Like + `--variable`, `--metadata` causes template variables to be set. + But unlike `--variable`, `--metadata` affects the metadata of the + underlying document (which is accessible from filters and may be + printed in some output formats). + +`--normalize` + +: Normalize the document after reading: merge adjacent + `Str` or `Emph` elements, for example, and remove repeated `Space`s. + +`-p`, `--preserve-tabs` + +: Preserve tabs instead of converting them to spaces (the default). + Note that this will only affect tabs in literal code spans and code + blocks; tabs in regular text will be treated as spaces. + +`--tab-stop=`*NUMBER* + +: Specify the number of spaces per tab (default is 4). + +`--track-changes=accept`|`reject`|`all` + +: Specifies what to do with insertions, deletions, and comments + produced by the MS Word "Track Changes" feature. `accept` (the + default), inserts all insertions, and ignores all + deletions. `reject` inserts all deletions and ignores + insertions. Both `accept` and `reject` ignore comments. `all` puts + in insertions, deletions, and comments, wrapped in spans with + `insertion`, `deletion`, `comment-start`, and `comment-end` + classes, respectively. The author and time of change is + included. `all` is useful for scripting: only accepting changes + from a certain reviewer, say, or before a certain date. This + option only affects the docx reader. + +`--extract-media=`*DIR* + +: Extract images and other media contained in a docx or epub container + to the path *DIR*, creating it if necessary, and adjust the images + references in the document so they point to the extracted files. + This option only affects the docx and epub readers. + +[`pandocfilters`]: https://github.com/jgm/pandocfilters +[PHP]: https://github.com/vinai/pandocfilters-php +[perl]: https://metacpan.org/pod/Pandoc::Filter +[javascript/node.js]: https://github.com/mvhenderson/pandoc-filter-node + +General writer options +---------------------- + +`-s`, `--standalone` + +: Produce output with an appropriate header and footer (e.g. a + standalone HTML, LaTeX, TEI, or RTF file, not a fragment). This option + is set automatically for `pdf`, `epub`, `epub3`, `fb2`, `docx`, and `odt` + output. + +`--template=`*FILE* + +: Use *FILE* as a custom template for the generated document. Implies + `--standalone`. See [Templates], below, for a description + of template syntax. If no extension is specified, an extension + corresponding to the writer will be added, so that `--template=special` + looks for `special.html` for HTML output. If the template is not + found, pandoc will search for it in the `templates` subdirectory of + the user data directory (see `--data-dir`). If this option is not used, + a default template appropriate for the output format will be used (see + `-D/--print-default-template`). + +`-V` *KEY*[`=`*VAL*], `--variable=`*KEY*[`:`*VAL*] + +: Set the template variable *KEY* to the value *VAL* when rendering the + document in standalone mode. This is generally only useful when the + `--template` option is used to specify a custom template, since + pandoc automatically sets the variables used in the default + templates. If no *VAL* is specified, the key will be given the + value `true`. + +`-D` *FORMAT*, `--print-default-template=`*FORMAT* + +: Print the system default template for an output *FORMAT*. (See `-t` + for a list of possible *FORMAT*s.) Templates in the user data + directory are ignored. + +`--print-default-data-file=`*FILE* + +: Print a system default data file. Files in the user data directory + are ignored. + +`--dpi`=*NUMBER* +: Specify the dpi (dots per inch) value for conversion from pixels + to inch/centimeters and vice versa. The default is 96dpi. + Technically, the correct term would be ppi (pixels per inch). + +`--wrap=auto`|`none`|`preserve` + +: Determine how text is wrapped in the output (the source + code, not the rendered version). With `auto` (the default), + pandoc will attempt to wrap lines to the column width specified by + `--columns` (default 80). With `none`, pandoc will not wrap + lines at all. With `preserve`, pandoc will attempt to + preserve the wrapping from the source document (that is, + where there are nonsemantic newlines in the source, there + will be nonsemantic newlines in the output as well). + +`--no-wrap` + +: Deprecated synonym for `--wrap=none`. + +`--columns=`*NUMBER* + +: Specify length of lines in characters. This affects text wrapping + in the generated source code (see `--wrap`). It also affects + calculation of column widths for plain text tables (see [Tables] below). + +`--toc`, `--table-of-contents` + +: Include an automatically generated table of contents (or, in + the case of `latex`, `context`, `docx`, and `rst`, an instruction to create + one) in the output document. This option has no effect on `man`, + `docbook`, `docbook5`, `slidy`, `slideous`, `s5`, or `odt` output. + +`--toc-depth=`*NUMBER* + +: Specify the number of section levels to include in the table + of contents. The default is 3 (which means that level 1, 2, and 3 + headers will be listed in the contents). + +`--no-highlight` + +: Disables syntax highlighting for code blocks and inlines, even when + a language attribute is given. + +`--highlight-style=`*STYLE* + +: Specifies the coloring style to be used in highlighted source code. + Options are `pygments` (the default), `kate`, `monochrome`, + `espresso`, `zenburn`, `haddock`, and `tango`. For more information + on syntax highlighting in pandoc, see [Syntax highlighting], below. + See also `--list-highlight-styles`. + +`-H` *FILE*, `--include-in-header=`*FILE* + +: Include contents of *FILE*, verbatim, at the end of the header. + This can be used, for example, to include special + CSS or javascript in HTML documents. This option can be used + repeatedly to include multiple files in the header. They will be + included in the order specified. Implies `--standalone`. + +`-B` *FILE*, `--include-before-body=`*FILE* + +: Include contents of *FILE*, verbatim, at the beginning of the + document body (e.g. after the `` tag in HTML, or the + `\begin{document}` command in LaTeX). This can be used to include + navigation bars or banners in HTML documents. This option can be + used repeatedly to include multiple files. They will be included in + the order specified. Implies `--standalone`. + +`-A` *FILE*, `--include-after-body=`*FILE* + +: Include contents of *FILE*, verbatim, at the end of the document + body (before the `` tag in HTML, or the + `\end{document}` command in LaTeX). This option can be used + repeatedly to include multiple files. They will be included in the + order specified. Implies `--standalone`. + +Options affecting specific writers +---------------------------------- + +`--self-contained` + +: Produce a standalone HTML file with no external dependencies, using + `data:` URIs to incorporate the contents of linked scripts, stylesheets, + images, and videos. The resulting file should be "self-contained," + in the sense that it needs no external files and no net access to be + displayed properly by a browser. This option works only with HTML output + formats, including `html`, `html5`, `html+lhs`, `html5+lhs`, `s5`, + `slidy`, `slideous`, `dzslides`, and `revealjs`. Scripts, images, and + stylesheets at absolute URLs will be downloaded; those at relative URLs + will be sought relative to the working directory (if the first source + file is local) or relative to the base URL (if the first source + file is remote). Limitation: resources that are loaded dynamically + through JavaScript cannot be incorporated; as a result, `--self-contained` + does not work with `--mathjax`, and some advanced features (e.g. + zoom or speaker notes) may not work in an offline "self-contained" + `reveal.js` slide show. + +`--html-q-tags` + +: Use `` tags for quotes in HTML. + +`--ascii` + +: Use only ascii characters in output. Currently supported only + for HTML output (which uses numerical entities instead of + UTF-8 when this option is selected). + +`--reference-links` + +: Use reference-style links, rather than inline links, in writing Markdown + or reStructuredText. By default inline links are used. The + placement of link references is affected by the + `--reference-location` option. + +`--reference-location = block`|`section`|`document` + +: Specify whether footnotes (and references, if `reference-links` is + set) are placed at the end of the current (top-level) block, the + current section, or the document. The default is + `document`. Currently only affects the markdown writer. + +`--atx-headers` + +: Use ATX-style headers in Markdown and asciidoc output. The default is + to use setext-style headers for levels 1-2, and then ATX headers. + +`--chapters` + +: Deprecated synonym for `--top-level-division=chapter`. + +`--top-level-division=[section|chapter|part]` + +: Treat top-level headers as the given division type in LaTeX, ConTeXt, + DocBook, and TEI output. The hierarchy order is part, chapter, then section; + all headers are shifted such that the top-level header becomes the specified + type. The default is `section`. When the LaTeX document class is set to + `report`, `book`, or `memoir` (unless the `article` option is specified), + `chapter` is implied as the setting for this option. If `beamer` is the + output format, specifying either `chapter` or `part` will cause top-level + headers to become `\part{..}`, while second-level headers remain as their + default type. + +`-N`, `--number-sections` + +: Number section headings in LaTeX, ConTeXt, HTML, or EPUB output. + By default, sections are not numbered. Sections with class + `unnumbered` will never be numbered, even if `--number-sections` + is specified. + +`--number-offset=`*NUMBER*[`,`*NUMBER*`,`*...*] + +: Offset for section headings in HTML output (ignored in other + output formats). The first number is added to the section number for + top-level headers, the second for second-level headers, and so on. + So, for example, if you want the first top-level header in your + document to be numbered "6", specify `--number-offset=5`. + If your document starts with a level-2 header which you want to + be numbered "1.5", specify `--number-offset=1,4`. + Offsets are 0 by default. Implies `--number-sections`. + +`--no-tex-ligatures` + +: Do not use the TeX ligatures for quotation marks, apostrophes, + and dashes (`` `...' ``, ` ``..'' `, `--`, `---`) when + writing or reading LaTeX or ConTeXt. In reading LaTeX, + parse the characters `` ` ``, `'`, and `-` literally, rather + than parsing ligatures for quotation marks and dashes. In + writing LaTeX or ConTeXt, print unicode quotation mark and + dash characters literally, rather than converting them to + the standard ASCII TeX ligatures. Note: normally `--smart` + is selected automatically for LaTeX and ConTeXt output, but + it must be specified explicitly if `--no-tex-ligatures` is + selected. If you use literal curly quotes, dashes, and + ellipses in your source, then you may want to use + `--no-tex-ligatures` without `--smart`. + +`--listings` + +: Use the [`listings`] package for LaTeX code blocks + +`-i`, `--incremental` + +: Make list items in slide shows display incrementally (one by one). + The default is for lists to be displayed all at once. + +`--slide-level=`*NUMBER* + +: Specifies that headers with the specified level create + slides (for `beamer`, `s5`, `slidy`, `slideous`, `dzslides`). Headers + above this level in the hierarchy are used to divide the + slide show into sections; headers below this level create + subheads within a slide. The default is to set the slide level + based on the contents of the document; see + [Structuring the slide show]. + +`--section-divs` + +: Wrap sections in `
` tags (or `
` tags in HTML5), + and attach identifiers to the enclosing `
` (or `
`) + rather than the header itself. See + [Header identifiers], below. + +`--email-obfuscation=none`|`javascript`|`references` + +: Specify a method for obfuscating `mailto:` links in HTML documents. + `none` leaves `mailto:` links as they are. `javascript` obfuscates + them using javascript. `references` obfuscates them by printing their + letters as decimal or hexadecimal character references. The default + is `none`. + +`--id-prefix=`*STRING* + +: Specify a prefix to be added to all automatically generated identifiers + in HTML and DocBook output, and to footnote numbers in Markdown output. + This is useful for preventing duplicate identifiers when generating + fragments to be included in other pages. + +`-T` *STRING*, `--title-prefix=`*STRING* + +: Specify *STRING* as a prefix at the beginning of the title + that appears in the HTML header (but not in the title as it + appears at the beginning of the HTML body). Implies + `--standalone`. + +`-c` *URL*, `--css=`*URL* + +: Link to a CSS style sheet. This option can be used repeatedly to + include multiple files. They will be included in the order specified. + +`--reference-odt=`*FILE* + +: Use the specified file as a style reference in producing an ODT. + For best results, the reference ODT should be a modified version + of an ODT produced using pandoc. The contents of the reference ODT + are ignored, but its stylesheets are used in the new ODT. If no + reference ODT is specified on the command line, pandoc will look + for a file `reference.odt` in the user data directory (see + `--data-dir`). If this is not found either, sensible defaults will be + used. + +`--reference-docx=`*FILE* + +: Use the specified file as a style reference in producing a docx file. + For best results, the reference docx should be a modified version + of a docx file produced using pandoc. The contents of the reference docx + are ignored, but its stylesheets and document properties (including + margins, page size, header, and footer) are used in the new docx. If no + reference docx is specified on the command line, pandoc will look + for a file `reference.docx` in the user data directory (see + `--data-dir`). If this is not found either, sensible defaults will be + used. The following styles are used by pandoc: [paragraph] + Normal, Body Text, First Paragraph, Compact, Title, Subtitle, Author, Date, + Abstract, Bibliography, Heading 1, Heading 2, Heading 3, Heading 4, + Heading 5, Heading 6, Block Text, Footnote Text, Definition Term, + Definition, Caption, Table Caption, Image Caption, Figure, + Figure With Caption, TOC Heading; + [character] Default Paragraph Font, Body Text Char, Verbatim Char, + Footnote Reference, Hyperlink; [table] Normal Table. + +`--epub-stylesheet=`*FILE* + +: Use the specified CSS file to style the EPUB. If no stylesheet + is specified, pandoc will look for a file `epub.css` in the + user data directory (see `--data-dir`). If it is not + found there, sensible defaults will be used. + +`--epub-cover-image=`*FILE* + +: Use the specified image as the EPUB cover. It is recommended + that the image be less than 1000px in width and height. Note that + in a Markdown source document you can also specify `cover-image` + in a YAML metadata block (see [EPUB Metadata], below). + +`--epub-metadata=`*FILE* + +: Look in the specified XML file for metadata for the EPUB. + The file should contain a series of [Dublin Core elements]. + For example: + + Creative Commons + es-AR + + By default, pandoc will include the following metadata elements: + `` (from the document title), `` (from the + document authors), `` (from the document date, which should + be in [ISO 8601 format]), `` (from the `lang` + variable, or, if is not set, the locale), and `` (a randomly generated UUID). Any of these may be + overridden by elements in the metadata file. + + Note: if the source document is Markdown, a YAML metadata block + in the document can be used instead. See below under + [EPUB Metadata]. + +`--epub-embed-font=`*FILE* + +: Embed the specified font in the EPUB. This option can be repeated + to embed multiple fonts. Wildcards can also be used: for example, + `DejaVuSans-*.ttf`. However, if you use wildcards on the command + line, be sure to escape them or put the whole filename in single quotes, + to prevent them from being interpreted by the shell. To use the + embedded fonts, you will need to add declarations like the following + to your CSS (see `--epub-stylesheet`): + + @font-face { + font-family: DejaVuSans; + font-style: normal; + font-weight: normal; + src:url("DejaVuSans-Regular.ttf"); + } + @font-face { + font-family: DejaVuSans; + font-style: normal; + font-weight: bold; + src:url("DejaVuSans-Bold.ttf"); + } + @font-face { + font-family: DejaVuSans; + font-style: italic; + font-weight: normal; + src:url("DejaVuSans-Oblique.ttf"); + } + @font-face { + font-family: DejaVuSans; + font-style: italic; + font-weight: bold; + src:url("DejaVuSans-BoldOblique.ttf"); + } + body { font-family: "DejaVuSans"; } + +`--epub-chapter-level=`*NUMBER* + +: Specify the header level at which to split the EPUB into separate + "chapter" files. The default is to split into chapters at level 1 + headers. This option only affects the internal composition of the + EPUB, not the way chapters and sections are displayed to users. Some + readers may be slow if the chapter files are too large, so for large + documents with few level 1 headers, one might want to use a chapter + level of 2 or 3. + +`--latex-engine=pdflatex`|`lualatex`|`xelatex` + +: Use the specified LaTeX engine when producing PDF output. + The default is `pdflatex`. If the engine is not in your PATH, + the full path of the engine may be specified here. + +`--latex-engine-opt=`*STRING* + +: Use the given string as a command-line argument to the `latex-engine`. + If used multiple times, the arguments are provided with spaces between + them. Note that no check for duplicate options is done. + +[Dublin Core elements]: http://dublincore.org/documents/dces/ +[ISO 8601 format]: http://www.w3.org/TR/NOTE-datetime + +Citation rendering +------------------ + +`--bibliography=`*FILE* + +: Set the `bibliography` field in the document's metadata to *FILE*, + overriding any value set in the metadata, and process citations + using `pandoc-citeproc`. (This is equivalent to + `--metadata bibliography=FILE --filter pandoc-citeproc`.) + If `--natbib` or `--biblatex` is also supplied, `pandoc-citeproc` is not + used, making this equivalent to `--metadata bibliography=FILE`. + If you supply this argument multiple times, each *FILE* will be added + to bibliography. + +`--csl=`*FILE* + +: Set the `csl` field in the document's metadata to *FILE*, + overriding any value set in the metadata. (This is equivalent to + `--metadata csl=FILE`.) + This option is only relevant with `pandoc-citeproc`. + +`--citation-abbreviations=`*FILE* + +: Set the `citation-abbreviations` field in the document's metadata to + *FILE*, overriding any value set in the metadata. (This is equivalent to + `--metadata citation-abbreviations=FILE`.) + This option is only relevant with `pandoc-citeproc`. + +`--natbib` + +: Use [`natbib`] for citations in LaTeX output. This option is not for use + with the `pandoc-citeproc` filter or with PDF output. It is intended for + use in producing a LaTeX file that can be processed with [`bibtex`]. + +`--biblatex` + +: Use [`biblatex`] for citations in LaTeX output. This option is not for use + with the `pandoc-citeproc` filter or with PDF output. It is intended for + use in producing a LaTeX file that can be processed with [`bibtex`] or [`biber`]. + +Math rendering in HTML +---------------------- + +`-m` [*URL*], `--latexmathml`[`=`*URL*] + +: Use the [LaTeXMathML] script to display embedded TeX math in HTML output. + To insert a link to a local copy of the `LaTeXMathML.js` script, + provide a *URL*. If no *URL* is provided, the contents of the + script will be inserted directly into the HTML header, preserving + portability at the price of efficiency. If you plan to use math on + several pages, it is much better to link to a copy of the script, + so it can be cached. + +`--mathml`[`=`*URL*] + +: Convert TeX math to [MathML] (in `docbook`, `docbook5`, `html` and `html5`). + In standalone `html` output, a small javascript (or a link to such a + script if a *URL* is supplied) will be inserted that allows the MathML to + be viewed on some browsers. + +`--jsmath`[`=`*URL*] + +: Use [jsMath] to display embedded TeX math in HTML output. + The *URL* should point to the jsMath load script (e.g. + `jsMath/easy/load.js`); if provided, it will be linked to in + the header of standalone HTML documents. If a *URL* is not provided, + no link to the jsMath load script will be inserted; it is then + up to the author to provide such a link in the HTML template. + +`--mathjax`[`=`*URL*] + +: Use [MathJax] to display embedded TeX math in HTML output. + The *URL* should point to the `MathJax.js` load script. + If a *URL* is not provided, a link to the MathJax CDN will + be inserted. + +`--gladtex` + +: Enclose TeX math in `` tags in HTML output. These can then + be processed by [gladTeX] to produce links to images of the typeset + formulas. + +`--mimetex`[`=`*URL*] + +: Render TeX math using the [mimeTeX] CGI script. If *URL* is not + specified, it is assumed that the script is at `/cgi-bin/mimetex.cgi`. + +`--webtex`[`=`*URL*] + +: Render TeX formulas using an external script that converts TeX + formulas to images. The formula will be concatenated with the URL + provided. If *URL* is not specified, the CodeCogs will be used. + Note: the `--webtex` option will affect Markdown output + as well as HTML, which is useful if you're targeting a + version of Markdown without native math support. + +`--katex`[`=`*URL*] + +: Use [KaTeX] to display embedded TeX math in HTML output. + The *URL* should point to the `katex.js` load script. If a *URL* is + not provided, a link to the KaTeX CDN will be inserted. + Note: [KaTeX] seems to work best with `html5` output. + +`--katex-stylesheet=`*URL* + +: The *URL* should point to the `katex.css` stylesheet. If this option is + not specified, a link to the KaTeX CDN will be inserted. Note that this + option does not imply `--katex`. + +[MathML]: http://www.w3.org/Math/ +[LaTeXMathML]: http://math.etsu.edu/LaTeXMathML/ +[jsMath]: http://www.math.union.edu/~dpvc/jsmath/ +[MathJax]: https://www.mathjax.org +[gladTeX]: http://ans.hsh.no/home/mgg/gladtex/ +[mimeTeX]: http://www.forkosh.com/mimetex.html +[KaTeX]: https://github.com/Khan/KaTeX + +Options for wrapper scripts +--------------------------- + +`--dump-args` + +: Print information about command-line arguments to *stdout*, then exit. + This option is intended primarily for use in wrapper scripts. + The first line of output contains the name of the output file specified + with the `-o` option, or `-` (for *stdout*) if no output file was + specified. The remaining lines contain the command-line arguments, + one per line, in the order they appear. These do not include regular + pandoc options and their arguments, but do include any options appearing + after a `--` separator at the end of the line. + +`--ignore-args` + +: Ignore command-line arguments (for use in wrapper scripts). + Regular pandoc options are not ignored. Thus, for example, + + pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1 + + is equivalent to + + pandoc -o foo.html -s + +Templates +========= + +When the `-s/--standalone` option is used, pandoc uses a template to +add header and footer material that is needed for a self-standing +document. To see the default template that is used, just type + + pandoc -D *FORMAT* + +where *FORMAT* is the name of the output format. A custom template +can be specified using the `--template` option. You can also override +the system default templates for a given output format *FORMAT* +by putting a file `templates/default.*FORMAT*` in the user data +directory (see `--data-dir`, above). *Exceptions:* + +- For `odt` output, customize the `default.opendocument` + template. +- For `pdf` output, customize the `default.latex` template + (or the `default.beamer` template, if you use `-t beamer`, + or the `default.context` template, if you use `-t context`). +- `docx` has no template (however, you can use + `--reference-docx` to customize the output). + +Templates contain *variables*, which allow for the inclusion of +arbitrary information at any point in the file. Variables may be set +within the document using [YAML metadata blocks][Extension: +`yaml_metadata_block`]. They may also be set at the +command line using the `-V/--variable` option: variables set in this +way override metadata fields with the same name. + +Variables set by pandoc +----------------------- + +Some variables are set automatically by pandoc. These vary somewhat +depending on the output format, but include metadata fields as well +as the following: + +`title`, `author`, `date` +: allow identification of basic aspects of the document. Included + in PDF metadata through LaTeX and ConTeXt. These can be set + through a [pandoc title block][Extension: `pandoc_title_block`], + which allows for multiple authors, or through a YAML metadata block: + + --- + author: + - Aristotle + - Peter Abelard + ... + +`subtitle` +: document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and Word docx; + renders in LaTeX only when using a document class that supports + `\subtitle`, such as `beamer` or the [KOMA-Script] series (`scrartcl`, + `scrreprt`, `scrbook`).[^subtitle] + +`institute` +: author affiliations (in LaTeX and Beamer only). Can be a + list, when there are multiple authors. + +`abstract` +: document summary, included in LaTeX, ConTeXt, AsciiDoc, and Word docx + +`keywords` +: list of keywords to be included in HTML, PDF, and AsciiDoc metadata; + may be repeated as for `author`, above + +`header-includes` +: contents specified by `-H/--include-in-header` (may have multiple + values) + +`toc` +: non-null value if `--toc/--table-of-contents` was specified + +`toc-title` +: title of table of contents (works only with EPUB and docx) + +`include-before` +: contents specified by `-B/--include-before-body` (may have + multiple values) + +`include-after` +: contents specified by `-A/--include-after-body` (may have + multiple values) + +`body` +: body of document + +`meta-json` +: JSON representation of all of the document's metadata + +[^subtitle]: To make `subtitle` work with other LaTeX + document classes, you can add the following to `header-includes`: + + \providecommand{\subtitle}[1]{% + \usepackage{titling} + \posttitle{% + \par\large#1\end{center}} + } + +Language variables +------------------ + +`lang` +: identifies the main language of the document, + using a code according to [BCP 47] (e.g. `en` or `en-GB`). + For some output formats, pandoc will convert it to an appropriate + format stored in the additional variables `babel-lang`, + `polyglossia-lang` (LaTeX) and `context-lang` (ConTeXt). + + Native pandoc `span`s and `div`s with the lang attribute + (value in BCP 47) can be used to switch the language in + that range. + +`otherlangs` +: a list of other languages used in the document + in the YAML metadata, according to [BCP 47]. For example: + `otherlangs: [en-GB, fr]`. + This is automatically generated from the `lang` attributes + in all `span`s and `div`s but can be overridden. + Currently only used by LaTeX through the generated + `babel-otherlangs` and `polyglossia-otherlangs` variables. + The LaTeX writer outputs polyglossia commands in the text but + the `babel-newcommands` variable contains mappings for them + to the corresponding babel. + +`dir` +: the base direction of the document, either `rtl` (right-to-left) + or `ltr` (left-to-right). + + For bidirectional documents, native pandoc `span`s and `div`s + with the `dir` attribute (value `rtl` or `ltr`) can be used to + override the base direction in some output formats. + This may not always be necessary if the final renderer + (e.g. the browser, when generating HTML) supports the + [Unicode Bidirectional Algorithm]. + + When using LaTeX for bidirectional documents, only the `xelatex` engine + is fully supported (use `--latex-engine=xelatex`). + +[BCP 47]: https://tools.ietf.org/html/bcp47 +[Unicode Bidirectional Algorithm]: http://www.w3.org/International/articles/inline-bidi-markup/uba-basics + +Variables for slides +-------------------- + +Variables are available for [producing slide shows with pandoc], +including all [reveal.js configuration options]. + +`slidy-url` +: base URL for Slidy documents (defaults to + `http://www.w3.org/Talks/Tools/Slidy2`) + +`slideous-url` +: base URL for Slideous documents (defaults to `slideous`) + +`s5-url` +: base URL for S5 documents (defaults to `s5/default`) + +`revealjs-url` +: base URL for reveal.js documents (defaults to `reveal.js`) + +`theme`, `colortheme`, `fonttheme`, `innertheme`, `outertheme` +: themes for LaTeX [`beamer`] documents + +`themeoptions` +: options for LaTeX beamer themes (a list). + +`navigation` +: controls navigation symbols in `beamer` documents + (default is `empty` for no navigation symbols; other valid values + are `frame`, `vertical`, and `horizontal`). + +`section-titles` +: enables on "title pages" for new sections in `beamer` + documents (default = true). + +`beamerarticle` +: when true, the `beamerarticle` package is loaded (for + producing an article from beamer slides). + +`colorlinks` +: add color to link text; automatically enabled if any of `linkcolor`, `citecolor`, + `urlcolor`, or `toccolor` are set (for beamer only). + +`linkcolor`, `citecolor`, `urlcolor`, `toccolor` +: color for internal links, citation links, external links, and links in table + of contents: uses any of the [predefined LaTeX colors] (for beamer only). + +[reveal.js configuration options]: https://github.com/hakimel/reveal.js#configuration + +Variables for LaTeX +------------------- + +LaTeX variables are used when [creating a PDF]. + +`papersize` +: paper size, e.g. `letter`, `A4` + +`fontsize` +: font size for body text (e.g. `10pt`, `12pt`) + +`documentclass` +: document class, e.g. [`article`], [`report`], [`book`], [`memoir`] + +`classoption` +: option for document class, e.g. `oneside`; may be repeated + for multiple options + +`geometry` +: option for [`geometry`] package, e.g. `margin=1in`; + may be repeated for multiple options + +`margin-left`, `margin-right`, `margin-top`, `margin-bottom` +: sets margins, if `geometry` is not used (otherwise `geometry` + overrides these) + +`linestretch` +: adjusts line spacing using the [`setspace`] + package, e.g. `1.25`, `1.5` + +`fontfamily` +: font package for use with `pdflatex`: + [TeX Live] includes many options, documented in the [LaTeX Font Catalogue]. + The default is [Latin Modern][`lm`]. + +`fontfamilyoptions` +: options for package used as `fontfamily`: e.g. `osf,sc` with + `fontfamily` set to [`mathpazo`] provides Palatino with old-style + figures and true small caps; may be repeated for multiple options + +`mainfont`, `sansfont`, `monofont`, `mathfont`, `CJKmainfont` +: font families for use with `xelatex` or + `lualatex`: take the name of any system font, using the + [`fontspec`] package. Note that if `CJKmainfont` is used, + the [`xecjk`] package must be available. + +`mainfontoptions`, `sansfontoptions`, `monofontoptions`, `mathfontoptions`, `CJKoptions` +: options to use with `mainfont`, `sansfont`, `monofont`, `mathfont`, + `CJKmainfont` in `xelatex` and `lualatex`. Allow for any choices + available through [`fontspec`], such as the OpenType features + `Numbers=OldStyle,Numbers=Proportional`. May be repeated for multiple options. + +`fontenc` +: allows font encoding to be specified through `fontenc` package (with `pdflatex`); + default is `T1` (see guide to [LaTeX font encodings]) + +`colorlinks` +: add color to link text; automatically enabled if any of `linkcolor`, `citecolor`, + `urlcolor`, or `toccolor` are set + +`linkcolor`, `citecolor`, `urlcolor`, `toccolor` +: color for internal links, citation links, external links, and links in table of contents: + uses any of the [predefined LaTeX colors] + +`links-as-notes` +: causes links to be printed as footnotes + +`indent` +: uses document class settings for indentation (the default LaTeX template + otherwise removes indentation and adds space between paragraphs) + +`subparagraph` +: disables default behavior of LaTeX template that redefines (sub)paragraphs + as sections, changing the appearance of nested headings in some classes + +`thanks` +: specifies contents of acknowledgments footnote after document title. + +`toc` +: include table of contents (can also be set using `--toc/--table-of-contents`) + +`toc-depth` +: level of section to include in table of contents + +`secnumdepth` +: numbering depth for sections, if sections are numbered + +`lof`, `lot` +: include list of figures, list of tables + +`bibliography` +: bibliography to use for resolving references + +`biblio-style` +: bibliography style, when used with `--natbib` and `--biblatex`. + +`biblio-title` +: bibliography title, when used with `--natbib` and `--biblatex`. + +`biblatexoptions` +: list of options for biblatex. + +[`article`]: https://ctan.org/pkg/article +[`report`]: https://ctan.org/pkg/report +[`book`]: https://ctan.org/pkg/book +[KOMA-Script]: https://ctan.org/pkg/koma-script +[`memoir`]: https://ctan.org/pkg/memoir +[predefined LaTeX colors]: https://en.wikibooks.org/wiki/LaTeX/Colors#Predefined_colors +[LaTeX Font Catalogue]: http://www.tug.dk/FontCatalogue/ +[`mathpazo`]: https://ctan.org/pkg/mathpazo +[LaTeX font encodings]: https://ctan.org/pkg/encguide + +Variables for ConTeXt +--------------------- + +`papersize` +: paper size, e.g. `letter`, `A4`, `landscape` (see [ConTeXt Paper Setup]); + may be repeated for multiple options + +`layout` +: options for page margins and text arrangement (see [ConTeXt Layout]); + may be repeated for multiple options + +`margin-left`, `margin-right`, `margin-top`, `margin-bottom` +: sets margins, if `layout` is not used (otherwise `layout` + overrides these) + +`fontsize` +: font size for body text (e.g. `10pt`, `12pt`) + +`mainfont`, `sansfont`, `monofont`, `mathfont` +: font families: take the name of any system font (see [ConTeXt Font Switching]) + +`linkcolor`, `contrastcolor` +: color for links outside and inside a page, e.g. `red`, `blue` (see [ConTeXt Color]) + +`linkstyle` +: typeface style for links, e.g. `normal`, `bold`, `slanted`, `boldslanted`, `type`, `cap`, `small` + +`indenting` +: controls indentation of paragraphs, e.g. `yes,small,next` (see [ConTeXt Indentation]); + may be repeated for multiple options + +`whitespace` +: spacing between paragraphs, e.g. `none`, `small` (using [`setupwhitespace`]) + +`interlinespace` +: adjusts line spacing, e.g. `4ex` (using [`setupinterlinespace`]); + may be repeated for multiple options + +`headertext`, `footertext` +: text to be placed in running header or footer (see [ConTeXt Headers and Footers]); + may be repeated up to four times for different placement + +`pagenumbering` +: page number style and location (using [`setuppagenumbering`]); + may be repeated for multiple options + +`toc` +: include table of contents (can also be set using `--toc/--table-of-contents`) + +`lof`, `lot` +: include list of figures, list of tables + +[ConTeXt Paper Setup]: http://wiki.contextgarden.net/PaperSetup +[ConTeXt Layout]: http://wiki.contextgarden.net/Layout +[ConTeXt Font Switching]: http://wiki.contextgarden.net/Font_Switching +[ConTeXt Color]: http://wiki.contextgarden.net/Color +[ConTeXt Headers and Footers]: http://wiki.contextgarden.net/Headers_and_Footers +[ConTeXt Indentation]: http://wiki.contextgarden.net/Indentation +[`setupwhitespace`]: http://wiki.contextgarden.net/Command/setupwhitespace +[`setupinterlinespace`]: http://wiki.contextgarden.net/Command/setupinterlinespace +[`setuppagenumbering`]: http://wiki.contextgarden.net/Command/setuppagenumbering + +Variables for man pages +----------------------- + +`section` +: section number in man pages + +`header` +: header in man pages + +`footer` +: footer in man pages + +`adjusting` +: adjusts text to left (`l`), right (`r`), center (`c`), + or both (`b`) margins + +`hyphenate` +: if `true` (the default), hyphenation will be used + +Using variables in templates +---------------------------- + +Variable names are sequences of alphanumerics, `-`, and `_`, +starting with a letter. A variable name surrounded by `$` signs +will be replaced by its value. For example, the string `$title$` in + + $title$ + +will be replaced by the document title. + +To write a literal `$` in a template, use `$$`. + +Templates may contain conditionals. The syntax is as follows: + + $if(variable)$ + X + $else$ + Y + $endif$ + +This will include `X` in the template if `variable` has a non-null +value; otherwise it will include `Y`. `X` and `Y` are placeholders for +any valid template text, and may include interpolated variables or other +conditionals. The `$else$` section may be omitted. + +When variables can have multiple values (for example, `author` in +a multi-author document), you can use the `$for$` keyword: + + $for(author)$ + + $endfor$ + +You can optionally specify a separator to be used between +consecutive items: + + $for(author)$$author$$sep$, $endfor$ + +A dot can be used to select a field of a variable that takes +an object as its value. So, for example: + + $author.name$ ($author.affiliation$) + +If you use custom templates, you may need to revise them as pandoc +changes. We recommend tracking the changes in the default templates, +and modifying your custom templates accordingly. An easy way to do this +is to fork the [pandoc-templates] repository and merge in changes after each +pandoc release. + +[pandoc-templates]: https://github.com/jgm/pandoc-templates + +Pandoc's Markdown +================= + +Pandoc understands an extended and slightly revised version of +John Gruber's [Markdown] syntax. This document explains the syntax, +noting differences from standard Markdown. Except where noted, these +differences can be suppressed by using the `markdown_strict` format instead +of `markdown`. An extensions can be enabled by adding `+EXTENSION` +to the format name and disabled by adding `-EXTENSION`. For example, +`markdown_strict+footnotes` is strict Markdown with footnotes +enabled, while `markdown-footnotes-pipe_tables` is pandoc's +Markdown without footnotes or pipe tables. + +Philosophy +---------- + +Markdown is designed to be easy to write, and, even more importantly, +easy to read: + +> A Markdown-formatted document should be publishable as-is, as plain +> text, without looking like it's been marked up with tags or formatting +> instructions. +> -- [John Gruber](http://daringfireball.net/projects/markdown/syntax#philosophy) + +This principle has guided pandoc's decisions in finding syntax for +tables, footnotes, and other extensions. + +There is, however, one respect in which pandoc's aims are different +from the original aims of Markdown. Whereas Markdown was originally +designed with HTML generation in mind, pandoc is designed for multiple +output formats. Thus, while pandoc allows the embedding of raw HTML, +it discourages it, and provides other, non-HTMLish ways of representing +important document elements like definition lists, tables, mathematics, and +footnotes. + +Paragraphs +---------- + +A paragraph is one or more lines of text followed by one or more blank lines. +Newlines are treated as spaces, so you can reflow your paragraphs as you like. +If you need a hard line break, put two or more spaces at the end of a line. + +#### Extension: `escaped_line_breaks` #### + +A backslash followed by a newline is also a hard line break. +Note: in multiline and grid table cells, this is the only way +to create a hard line break, since trailing spaces in the cells +are ignored. + +Headers +------- + +There are two kinds of headers: Setext and ATX. + +### Setext-style headers ### + +A setext-style header is a line of text "underlined" with a row of `=` signs +(for a level one header) or `-` signs (for a level two header): + + A level-one header + ================== + + A level-two header + ------------------ + +The header text can contain inline formatting, such as emphasis (see +[Inline formatting], below). + + +### ATX-style headers ### + +An ATX-style header consists of one to six `#` signs and a line of +text, optionally followed by any number of `#` signs. The number of +`#` signs at the beginning of the line is the header level: + + ## A level-two header + + ### A level-three header ### + +As with setext-style headers, the header text can contain formatting: + + # A level-one header with a [link](/url) and *emphasis* + +#### Extension: `blank_before_header` #### + +Standard Markdown syntax does not require a blank line before a header. +Pandoc does require this (except, of course, at the beginning of the +document). The reason for the requirement is that it is all too easy for a +`#` to end up at the beginning of a line by accident (perhaps through line +wrapping). Consider, for example: + + I like several of their flavors of ice cream: + #22, for example, and #5. + + +### Header identifiers ### + +#### Extension: `header_attributes` #### + +Headers can be assigned attributes using this syntax at the end +of the line containing the header text: + + {#identifier .class .class key=value key=value} + +Thus, for example, the following headers will all be assigned the identifier +`foo`: + + # My header {#foo} + + ## My header ## {#foo} + + My other header {#foo} + --------------- + +(This syntax is compatible with [PHP Markdown Extra].) + +Note that although this syntax allows assignment of classes and key/value +attributes, writers generally don't use all of this information. Identifiers, +classes, and key/value attributes are used in HTML and HTML-based formats such +as EPUB and slidy. Identifiers are used for labels and link anchors in the +LaTeX, ConTeXt, Textile, and AsciiDoc writers. + +Headers with the class `unnumbered` will not be numbered, even if +`--number-sections` is specified. A single hyphen (`-`) in an attribute +context is equivalent to `.unnumbered`, and preferable in non-English +documents. So, + + # My header {-} + +is just the same as + + # My header {.unnumbered} + +#### Extension: `auto_identifiers` #### + +A header without an explicitly specified identifier will be +automatically assigned a unique identifier based on the header text. +To derive the identifier from the header text, + + - Remove all formatting, links, etc. + - Remove all footnotes. + - Remove all punctuation, except underscores, hyphens, and periods. + - Replace all spaces and newlines with hyphens. + - Convert all alphabetic characters to lowercase. + - Remove everything up to the first letter (identifiers may + not begin with a number or punctuation mark). + - If nothing is left after this, use the identifier `section`. + +Thus, for example, + + Header Identifier + ------------------------------- ---------------------------- + `Header identifiers in HTML` `header-identifiers-in-html` + `*Dogs*?--in *my* house?` `dogs--in-my-house` + `[HTML], [S5], or [RTF]?` `html-s5-or-rtf` + `3. Applications` `applications` + `33` `section` + +These rules should, in most cases, allow one to determine the identifier +from the header text. The exception is when several headers have the +same text; in this case, the first will get an identifier as described +above; the second will get the same identifier with `-1` appended; the +third with `-2`; and so on. + +These identifiers are used to provide link targets in the table of +contents generated by the `--toc|--table-of-contents` option. They +also make it easy to provide links from one section of a document to +another. A link to this section, for example, might look like this: + + See the section on + [header identifiers](#header-identifiers-in-html-latex-and-context). + +Note, however, that this method of providing links to sections works +only in HTML, LaTeX, and ConTeXt formats. + +If the `--section-divs` option is specified, then each section will +be wrapped in a `div` (or a `section`, if `--html5` was specified), +and the identifier will be attached to the enclosing `
` +(or `
`) tag rather than the header itself. This allows entire +sections to be manipulated using javascript or treated differently in +CSS. + +#### Extension: `implicit_header_references` #### + +Pandoc behaves as if reference links have been defined for each header. +So, to link to a header + + # Header identifiers in HTML + +you can simply write + + [Header identifiers in HTML] + +or + + [Header identifiers in HTML][] + +or + + [the section on header identifiers][header identifiers in + HTML] + +instead of giving the identifier explicitly: + + [Header identifiers in HTML](#header-identifiers-in-html) + +If there are multiple headers with identical text, the corresponding +reference will link to the first one only, and you will need to use explicit +links to link to the others, as described above. + +Like regular reference links, these references are case-insensitive. + +Explicit link reference definitions always take priority over +implicit header references. So, in the following example, the +link will point to `bar`, not to `#foo`: + + # Foo + + [foo]: bar + + See [foo] + +Block quotations +---------------- + +Markdown uses email conventions for quoting blocks of text. +A block quotation is one or more paragraphs or other block elements +(such as lists or headers), with each line preceded by a `>` character +and an optional space. (The `>` need not start at the left margin, but +it should not be indented more than three spaces.) + + > This is a block quote. This + > paragraph has two lines. + > + > 1. This is a list inside a block quote. + > 2. Second item. + +A "lazy" form, which requires the `>` character only on the first +line of each block, is also allowed: + + > This is a block quote. This + paragraph has two lines. + + > 1. This is a list inside a block quote. + 2. Second item. + +Among the block elements that can be contained in a block quote are +other block quotes. That is, block quotes can be nested: + + > This is a block quote. + > + > > A block quote within a block quote. + +If the `>` character is followed by an optional space, that space +will be considered part of the block quote marker and not part of +the indentation of the contents. Thus, to put an indented code +block in a block quote, you need five spaces after the `>`: + + > code + +#### Extension: `blank_before_blockquote` #### + +Standard Markdown syntax does not require a blank line before a block +quote. Pandoc does require this (except, of course, at the beginning of the +document). The reason for the requirement is that it is all too easy for a +`>` to end up at the beginning of a line by accident (perhaps through line +wrapping). So, unless the `markdown_strict` format is used, the following does +not produce a nested block quote in pandoc: + + > This is a block quote. + >> Nested. + + +Verbatim (code) blocks +---------------------- + +### Indented code blocks ### + +A block of text indented four spaces (or one tab) is treated as verbatim +text: that is, special characters do not trigger special formatting, +and all spaces and line breaks are preserved. For example, + + if (a > 3) { + moveShip(5 * gravity, DOWN); + } + +The initial (four space or one tab) indentation is not considered part +of the verbatim text, and is removed in the output. + +Note: blank lines in the verbatim text need not begin with four spaces. + + +### Fenced code blocks ### + +#### Extension: `fenced_code_blocks` #### + +In addition to standard indented code blocks, pandoc supports +*fenced* code blocks. These begin with a row of three or more +tildes (`~`) and end with a row of tildes that must be at least as long as +the starting row. Everything between these lines is treated as code. No +indentation is necessary: + + ~~~~~~~ + if (a > 3) { + moveShip(5 * gravity, DOWN); + } + ~~~~~~~ + +Like regular code blocks, fenced code blocks must be separated +from surrounding text by blank lines. + +If the code itself contains a row of tildes or backticks, just use a longer +row of tildes or backticks at the start and end: + + ~~~~~~~~~~~~~~~~ + ~~~~~~~~~~ + code including tildes + ~~~~~~~~~~ + ~~~~~~~~~~~~~~~~ + +#### Extension: `backtick_code_blocks` #### + +Same as `fenced_code_blocks`, but uses backticks (`` ` ``) instead of tildes +(`~`). + +#### Extension: `fenced_code_attributes` #### + +Optionally, you may attach attributes to fenced or backtick code block using +this syntax: + + ~~~~ {#mycode .haskell .numberLines startFrom="100"} + qsort [] = [] + qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++ + qsort (filter (>= x) xs) + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Here `mycode` is an identifier, `haskell` and `numberLines` are classes, and +`startFrom` is an attribute with value `100`. Some output formats can use this +information to do syntax highlighting. Currently, the only output formats +that uses this information are HTML and LaTeX. If highlighting is supported +for your output format and language, then the code block above will appear +highlighted, with numbered lines. (To see which languages are supported, do +`pandoc --version`.) Otherwise, the code block above will appear as follows: + + 
+      
+      ...
+      
+
+ +A shortcut form can also be used for specifying the language of +the code block: + + ```haskell + qsort [] = [] + ``` + +This is equivalent to: + + ``` {.haskell} + qsort [] = [] + ``` + +If the `fenced_code_attributes` extension is disabled, but +input contains class attribute(s) for the codeblock, the first +class attribute will be printed after the opening fence as a bare +word. + +To prevent all highlighting, use the `--no-highlight` flag. +To set the highlighting style, use `--highlight-style`. +For more information on highlighting, see [Syntax highlighting], +below. + +Line blocks +----------- + +#### Extension: `line_blocks` #### + +A line block is a sequence of lines beginning with a vertical bar (`|`) +followed by a space. The division into lines will be preserved in +the output, as will any leading spaces; otherwise, the lines will +be formatted as Markdown. This is useful for verse and addresses: + + | The limerick packs laughs anatomical + | In space that is quite economical. + | But the good ones I've seen + | So seldom are clean + | And the clean ones so seldom are comical + + | 200 Main St. + | Berkeley, CA 94718 + +The lines can be hard-wrapped if needed, but the continuation +line must begin with a space. + + | The Right Honorable Most Venerable and Righteous Samuel L. + Constable, Jr. + | 200 Main St. + | Berkeley, CA 94718 + +This syntax is borrowed from [reStructuredText]. + +Lists +----- + +### Bullet lists ### + +A bullet list is a list of bulleted list items. A bulleted list +item begins with a bullet (`*`, `+`, or `-`). Here is a simple +example: + + * one + * two + * three + +This will produce a "compact" list. If you want a "loose" list, in which +each item is formatted as a paragraph, put spaces between the items: + + * one + + * two + + * three + +The bullets need not be flush with the left margin; they may be +indented one, two, or three spaces. The bullet must be followed +by whitespace. + +List items look best if subsequent lines are flush with the first +line (after the bullet): + + * here is my first + list item. + * and my second. + +But Markdown also allows a "lazy" format: + + * here is my first + list item. + * and my second. + +### The four-space rule ### + +A list item may contain multiple paragraphs and other block-level +content. However, subsequent paragraphs must be preceded by a blank line +and indented four spaces or a tab. The list will look better if the first +paragraph is aligned with the rest: + + * First paragraph. + + Continued. + + * Second paragraph. With a code block, which must be indented + eight spaces: + + { code } + +List items may include other lists. In this case the preceding blank +line is optional. The nested list must be indented four spaces or +one tab: + + * fruits + + apples + - macintosh + - red delicious + + pears + + peaches + * vegetables + + broccoli + + chard + +As noted above, Markdown allows you to write list items "lazily," instead of +indenting continuation lines. However, if there are multiple paragraphs or +other blocks in a list item, the first line of each must be indented. + + + A lazy, lazy, list + item. + + + Another one; this looks + bad but is legal. + + Second paragraph of second + list item. + +**Note:** Although the four-space rule for continuation paragraphs +comes from the official [Markdown syntax guide], the reference implementation, +`Markdown.pl`, does not follow it. So pandoc will give different results than +`Markdown.pl` when authors have indented continuation paragraphs fewer than +four spaces. + +The [Markdown syntax guide] is not explicit whether the four-space +rule applies to *all* block-level content in a list item; it only +mentions paragraphs and code blocks. But it implies that the rule +applies to all block-level content (including nested lists), and +pandoc interprets it that way. + + [Markdown syntax guide]: + http://daringfireball.net/projects/markdown/syntax#list + +### Ordered lists ### + +Ordered lists work just like bulleted lists, except that the items +begin with enumerators rather than bullets. + +In standard Markdown, enumerators are decimal numbers followed +by a period and a space. The numbers themselves are ignored, so +there is no difference between this list: + + 1. one + 2. two + 3. three + +and this one: + + 5. one + 7. two + 1. three + +#### Extension: `fancy_lists` #### + +Unlike standard Markdown, pandoc allows ordered list items to be marked +with uppercase and lowercase letters and roman numerals, in addition to +arabic numerals. List markers may be enclosed in parentheses or followed by a +single right-parentheses or period. They must be separated from the +text that follows by at least one space, and, if the list marker is a +capital letter with a period, by at least two spaces.[^2] + +[^2]: The point of this rule is to ensure that normal paragraphs + starting with people's initials, like + + B. Russell was an English philosopher. + + do not get treated as list items. + + This rule will not prevent + + (C) 2007 Joe Smith + + from being interpreted as a list item. In this case, a backslash + escape can be used: + + (C\) 2007 Joe Smith + +The `fancy_lists` extension also allows '`#`' to be used as an +ordered list marker in place of a numeral: + + #. one + #. two + +#### Extension: `startnum` #### + +Pandoc also pays attention to the type of list marker used, and to the +starting number, and both of these are preserved where possible in the +output format. Thus, the following yields a list with numbers followed +by a single parenthesis, starting with 9, and a sublist with lowercase +roman numerals: + + 9) Ninth + 10) Tenth + 11) Eleventh + i. subone + ii. subtwo + iii. subthree + +Pandoc will start a new list each time a different type of list +marker is used. So, the following will create three lists: + + (2) Two + (5) Three + 1. Four + * Five + +If default list markers are desired, use `#.`: + + #. one + #. two + #. three + + +### Definition lists ### + +#### Extension: `definition_lists` #### + +Pandoc supports definition lists, using the syntax of +[PHP Markdown Extra] with some extensions.[^3] + + Term 1 + + : Definition 1 + + Term 2 with *inline markup* + + : Definition 2 + + { some code, part of Definition 2 } + + Third paragraph of definition 2. + +Each term must fit on one line, which may optionally be followed by +a blank line, and must be followed by one or more definitions. +A definition begins with a colon or tilde, which may be indented one +or two spaces. + +A term may have multiple definitions, and each definition may consist of one or +more block elements (paragraph, code block, list, etc.), each indented four +spaces or one tab stop. The body of the definition (including the first line, +aside from the colon or tilde) should be indented four spaces. However, +as with other Markdown lists, you can "lazily" omit indentation except +at the beginning of a paragraph or other block element: + + Term 1 + + : Definition + with lazy continuation. + + Second paragraph of the definition. + +If you leave space before the definition (as in the example above), +the text of the definition will be treated as a paragraph. In some +output formats, this will mean greater spacing between term/definition +pairs. For a more compact definition list, omit the space before the +definition: + + Term 1 + ~ Definition 1 + + Term 2 + ~ Definition 2a + ~ Definition 2b + +Note that space between items in a definition list is required. +(A variant that loosens this requirement, but disallows "lazy" +hard wrapping, can be activated with `compact_definition_lists`: see +[Non-pandoc extensions], below.) + +[^3]: I have been influenced by the suggestions of [David Wheeler](http://www.justatheory.com/computers/markup/modest-markdown-proposal.html). + +### Numbered example lists ### + +#### Extension: `example_lists` #### + +The special list marker `@` can be used for sequentially numbered +examples. The first list item with a `@` marker will be numbered '1', +the next '2', and so on, throughout the document. The numbered examples +need not occur in a single list; each new list using `@` will take up +where the last stopped. So, for example: + + (@) My first example will be numbered (1). + (@) My second example will be numbered (2). + + Explanation of examples. + + (@) My third example will be numbered (3). + +Numbered examples can be labeled and referred to elsewhere in the +document: + + (@good) This is a good example. + + As (@good) illustrates, ... + +The label can be any string of alphanumeric characters, underscores, +or hyphens. + + +### Compact and loose lists ### + +Pandoc behaves differently from `Markdown.pl` on some "edge +cases" involving lists. Consider this source: + + + First + + Second: + - Fee + - Fie + - Foe + + + Third + +Pandoc transforms this into a "compact list" (with no `

` tags around +"First", "Second", or "Third"), while Markdown puts `

` tags around +"Second" and "Third" (but not "First"), because of the blank space +around "Third". Pandoc follows a simple rule: if the text is followed by +a blank line, it is treated as a paragraph. Since "Second" is followed +by a list, and not a blank line, it isn't treated as a paragraph. The +fact that the list is followed by a blank line is irrelevant. (Note: +Pandoc works this way even when the `markdown_strict` format is specified. This +behavior is consistent with the official Markdown syntax description, +even though it is different from that of `Markdown.pl`.) + + +### Ending a list ### + +What if you want to put an indented code block after a list? + + - item one + - item two + + { my code block } + +Trouble! Here pandoc (like other Markdown implementations) will treat +`{ my code block }` as the second paragraph of item two, and not as +a code block. + +To "cut off" the list after item two, you can insert some non-indented +content, like an HTML comment, which won't produce visible output in +any format: + + - item one + - item two + + + + { my code block } + +You can use the same trick if you want two consecutive lists instead +of one big list: + + 1. one + 2. two + 3. three + + + + 1. uno + 2. dos + 3. tres + +Horizontal rules +---------------- + +A line containing a row of three or more `*`, `-`, or `_` characters +(optionally separated by spaces) produces a horizontal rule: + + * * * * + + --------------- + + +Tables +------ + +Four kinds of tables may be used. The first three kinds presuppose the use of +a fixed-width font, such as Courier. The fourth kind can be used with +proportionally spaced fonts, as it does not require lining up columns. + +#### Extension: `table_captions` #### + +A caption may optionally be provided with all 4 kinds of tables (as +illustrated in the examples below). A caption is a paragraph beginning +with the string `Table:` (or just `:`), which will be stripped off. +It may appear either before or after the table. + +#### Extension: `simple_tables` #### + +Simple tables look like this: + + Right Left Center Default + ------- ------ ---------- ------- + 12 12 12 12 + 123 123 123 123 + 1 1 1 1 + + Table: Demonstration of simple table syntax. + +The headers and table rows must each fit on one line. Column +alignments are determined by the position of the header text relative +to the dashed line below it:[^4] + + - If the dashed line is flush with the header text on the right side + but extends beyond it on the left, the column is right-aligned. + - If the dashed line is flush with the header text on the left side + but extends beyond it on the right, the column is left-aligned. + - If the dashed line extends beyond the header text on both sides, + the column is centered. + - If the dashed line is flush with the header text on both sides, + the default alignment is used (in most cases, this will be left). + +[^4]: This scheme is due to Michel Fortin, who proposed it on the + [Markdown discussion list](http://six.pairlist.net/pipermail/markdown-discuss/2005-March/001097.html). + +The table must end with a blank line, or a line of dashes followed by +a blank line. + +The column headers may be omitted, provided a dashed line is used +to end the table. For example: + + ------- ------ ---------- ------- + 12 12 12 12 + 123 123 123 123 + 1 1 1 1 + ------- ------ ---------- ------- + +When headers are omitted, column alignments are determined on the basis +of the first line of the table body. So, in the tables above, the columns +would be right, left, center, and right aligned, respectively. + +#### Extension: `multiline_tables` #### + +Multiline tables allow headers and table rows to span multiple lines +of text (but cells that span multiple columns or rows of the table are +not supported). Here is an example: + + ------------------------------------------------------------- + Centered Default Right Left + Header Aligned Aligned Aligned + ----------- ------- --------------- ------------------------- + First row 12.0 Example of a row that + spans multiple lines. + + Second row 5.0 Here's another one. Note + the blank line between + rows. + ------------------------------------------------------------- + + Table: Here's the caption. It, too, may span + multiple lines. + +These work like simple tables, but with the following differences: + + - They must begin with a row of dashes, before the header text + (unless the headers are omitted). + - They must end with a row of dashes, then a blank line. + - The rows must be separated by blank lines. + +In multiline tables, the table parser pays attention to the widths of +the columns, and the writers try to reproduce these relative widths in +the output. So, if you find that one of the columns is too narrow in the +output, try widening it in the Markdown source. + +Headers may be omitted in multiline tables as well as simple tables: + + ----------- ------- --------------- ------------------------- + First row 12.0 Example of a row that + spans multiple lines. + + Second row 5.0 Here's another one. Note + the blank line between + rows. + ----------- ------- --------------- ------------------------- + + : Here's a multiline table without headers. + +It is possible for a multiline table to have just one row, but the row +should be followed by a blank line (and then the row of dashes that ends +the table), or the table may be interpreted as a simple table. + +#### Extension: `grid_tables` #### + +Grid tables look like this: + + : Sample grid table. + + +---------------+---------------+--------------------+ + | Fruit | Price | Advantages | + +===============+===============+====================+ + | Bananas | $1.34 | - built-in wrapper | + | | | - bright color | + +---------------+---------------+--------------------+ + | Oranges | $2.10 | - cures scurvy | + | | | - tasty | + +---------------+---------------+--------------------+ + +The row of `=`s separates the header from the table body, and can be +omitted for a headerless table. The cells of grid tables may contain +arbitrary block elements (multiple paragraphs, code blocks, lists, +etc.). Alignments are not supported, nor are cells that span multiple +columns or rows. Grid tables can be created easily using [Emacs table mode]. + +[Emacs table mode]: http://table.sourceforge.net/ + +#### Extension: `pipe_tables` #### + +Pipe tables look like this: + + | Right | Left | Default | Center | + |------:|:-----|---------|:------:| + | 12 | 12 | 12 | 12 | + | 123 | 123 | 123 | 123 | + | 1 | 1 | 1 | 1 | + + : Demonstration of pipe table syntax. + +The syntax is identical to [PHP Markdown Extra tables]. The beginning and +ending pipe characters are optional, but pipes are required between all +columns. The colons indicate column alignment as shown. The header +cannot be omitted. To simulate a headerless table, include a header +with blank cells. + +Since the pipes indicate column boundaries, columns need not be vertically +aligned, as they are in the above example. So, this is a perfectly +legal (though ugly) pipe table: + + fruit| price + -----|-----: + apple|2.05 + pear|1.37 + orange|3.09 + +The cells of pipe tables cannot contain block elements like paragraphs +and lists, and cannot span multiple lines. If a pipe table contains a +row whose printable content is wider than the column width (see +`--columns`), then the cell contents will wrap, with the +relative cell widths determined by the widths of the separator +lines. + +Note: pandoc also recognizes pipe tables of the following +form, as can be produced by Emacs' orgtbl-mode: + + | One | Two | + |-----+-------| + | my | table | + | is | nice | + +The difference is that `+` is used instead of `|`. Other orgtbl features +are not supported. In particular, to get non-default column alignment, +you'll need to add colons as above. + +[PHP Markdown Extra tables]: https://michelf.ca/projects/php-markdown/extra/#table + +Metadata blocks +--------------- + +#### Extension: `pandoc_title_block` #### + +If the file begins with a title block + + % title + % author(s) (separated by semicolons) + % date + +it will be parsed as bibliographic information, not regular text. (It +will be used, for example, in the title of standalone LaTeX or HTML +output.) The block may contain just a title, a title and an author, +or all three elements. If you want to include an author but no +title, or a title and a date but no author, you need a blank line: + + % + % Author + + % My title + % + % June 15, 2006 + +The title may occupy multiple lines, but continuation lines must +begin with leading space, thus: + + % My title + on multiple lines + +If a document has multiple authors, the authors may be put on +separate lines with leading space, or separated by semicolons, or +both. So, all of the following are equivalent: + + % Author One + Author Two + + % Author One; Author Two + + % Author One; + Author Two + +The date must fit on one line. + +All three metadata fields may contain standard inline formatting +(italics, links, footnotes, etc.). + +Title blocks will always be parsed, but they will affect the output only +when the `--standalone` (`-s`) option is chosen. In HTML output, titles +will appear twice: once in the document head -- this is the title that +will appear at the top of the window in a browser -- and once at the +beginning of the document body. The title in the document head can have +an optional prefix attached (`--title-prefix` or `-T` option). The title +in the body appears as an H1 element with class "title", so it can be +suppressed or reformatted with CSS. If a title prefix is specified with +`-T` and no title block appears in the document, the title prefix will +be used by itself as the HTML title. + +The man page writer extracts a title, man page section number, and +other header and footer information from the title line. The title +is assumed to be the first word on the title line, which may optionally +end with a (single-digit) section number in parentheses. (There should +be no space between the title and the parentheses.) Anything after +this is assumed to be additional footer and header text. A single pipe +character (`|`) should be used to separate the footer text from the header +text. Thus, + + % PANDOC(1) + +will yield a man page with the title `PANDOC` and section 1. + + % PANDOC(1) Pandoc User Manuals + +will also have "Pandoc User Manuals" in the footer. + + % PANDOC(1) Pandoc User Manuals | Version 4.0 + +will also have "Version 4.0" in the header. + +#### Extension: `yaml_metadata_block` #### + +A YAML metadata block is a valid YAML object, delimited by a line of three +hyphens (`---`) at the top and a line of three hyphens (`---`) or three dots +(`...`) at the bottom. A YAML metadata block may occur anywhere in the +document, but if it is not at the beginning, it must be preceded by a blank +line. (Note that, because of the way pandoc concatenates input files when +several are provided, you may also keep the metadata in a separate YAML file +and pass it to pandoc as an argument, along with your Markdown files: + + pandoc chap1.md chap2.md chap3.md metadata.yaml -s -o book.html + +Just be sure that the YAML file begins with `---` and ends with `---` or +`...`.) + +Metadata will be taken from the fields of the YAML object and added to any +existing document metadata. Metadata can contain lists and objects (nested +arbitrarily), but all string scalars will be interpreted as Markdown. Fields +with names ending in an underscore will be ignored by pandoc. (They may be +given a role by external processors.) + +A document may contain multiple metadata blocks. The metadata fields will +be combined through a *left-biased union*: if two metadata blocks attempt +to set the same field, the value from the first block will be taken. + +When pandoc is used with `-t markdown` to create a Markdown document, +a YAML metadata block will be produced only if the `-s/--standalone` +option is used. All of the metadata will appear in a single block +at the beginning of the document. + +Note that YAML escaping rules must be followed. Thus, for example, +if a title contains a colon, it must be quoted. The pipe character +(`|`) can be used to begin an indented block that will be interpreted +literally, without need for escaping. This form is necessary +when the field contains blank lines: + + --- + title: 'This is the title: it contains a colon' + author: + - Author One + - Author Two + tags: [nothing, nothingness] + abstract: | + This is the abstract. + + It consists of two paragraphs. + ... + +Template variables will be set automatically from the metadata. Thus, for +example, in writing HTML, the variable `abstract` will be set to the HTML +equivalent of the Markdown in the `abstract` field: + +

This is the abstract.

+

It consists of two paragraphs.

+ +Variables can contain arbitrary YAML structures, but the template must match +this structure. The `author` variable in the default templates expects a +simple list or string, but can be changed to support more complicated +structures. The following combination, for example, would add an affiliation +to the author if one is given: + + --- + title: The document title + author: + - name: Author One + affiliation: University of Somewhere + - name: Author Two + affiliation: University of Nowhere + ... + +To use the structured authors in the example above, you would need a custom +template: + + $for(author)$ + $if(author.name)$ + $author.name$$if(author.affiliation)$ ($author.affiliation$)$endif$ + $else$ + $author$ + $endif$ + $endfor$ + + +Backslash escapes +----------------- + +#### Extension: `all_symbols_escapable` #### + +Except inside a code block or inline code, any punctuation or space +character preceded by a backslash will be treated literally, even if it +would normally indicate formatting. Thus, for example, if one writes + + *\*hello\** + +one will get + + *hello* + +instead of + + hello + +This rule is easier to remember than standard Markdown's rule, +which allows only the following characters to be backslash-escaped: + + \`*_{}[]()>#+-.! + +(However, if the `markdown_strict` format is used, the standard Markdown rule +will be used.) + +A backslash-escaped space is parsed as a nonbreaking space. It will +appear in TeX output as `~` and in HTML and XML as `\ ` or +`\ `. + +A backslash-escaped newline (i.e. a backslash occurring at the end of +a line) is parsed as a hard line break. It will appear in TeX output as +`\\` and in HTML as `
`. This is a nice alternative to +Markdown's "invisible" way of indicating hard line breaks using +two trailing spaces on a line. + +Backslash escapes do not work in verbatim contexts. + +Smart punctuation +----------------- + +#### Extension #### + +If the `--smart` option is specified, pandoc will produce typographically +correct output, converting straight quotes to curly quotes, `---` to +em-dashes, `--` to en-dashes, and `...` to ellipses. Nonbreaking spaces +are inserted after certain abbreviations, such as "Mr." + +Note: if your LaTeX template or any included header file call for the +[`csquotes`] package, pandoc will detect this automatically and use +`\enquote{...}` for quoted text. + +Inline formatting +----------------- + +### Emphasis ### + +To *emphasize* some text, surround it with `*`s or `_`, like this: + + This text is _emphasized with underscores_, and this + is *emphasized with asterisks*. + +Double `*` or `_` produces **strong emphasis**: + + This is **strong emphasis** and __with underscores__. + +A `*` or `_` character surrounded by spaces, or backslash-escaped, +will not trigger emphasis: + + This is * not emphasized *, and \*neither is this\*. + +#### Extension: `intraword_underscores` #### + +Because `_` is sometimes used inside words and identifiers, +pandoc does not interpret a `_` surrounded by alphanumeric +characters as an emphasis marker. If you want to emphasize +just part of a word, use `*`: + + feas*ible*, not feas*able*. + + +### Strikeout ### + +#### Extension: `strikeout` #### + +To strikeout a section of text with a horizontal line, begin and end it +with `~~`. Thus, for example, + + This ~~is deleted text.~~ + + +### Superscripts and subscripts ### + +#### Extension: `superscript`, `subscript` #### + +Superscripts may be written by surrounding the superscripted text by `^` +characters; subscripts may be written by surrounding the subscripted +text by `~` characters. Thus, for example, + + H~2~O is a liquid. 2^10^ is 1024. + +If the superscripted or subscripted text contains spaces, these spaces +must be escaped with backslashes. (This is to prevent accidental +superscripting and subscripting through the ordinary use of `~` and `^`.) +Thus, if you want the letter P with 'a cat' in subscripts, use +`P~a\ cat~`, not `P~a cat~`. + + +### Verbatim ### + +To make a short span of text verbatim, put it inside backticks: + + What is the difference between `>>=` and `>>`? + +If the verbatim text includes a backtick, use double backticks: + + Here is a literal backtick `` ` ``. + +(The spaces after the opening backticks and before the closing +backticks will be ignored.) + +The general rule is that a verbatim span starts with a string +of consecutive backticks (optionally followed by a space) +and ends with a string of the same number of backticks (optionally +preceded by a space). + +Note that backslash-escapes (and other Markdown constructs) do not +work in verbatim contexts: + + This is a backslash followed by an asterisk: `\*`. + +#### Extension: `inline_code_attributes` #### + +Attributes can be attached to verbatim text, just as with +[fenced code blocks]: + + `<$>`{.haskell} + +### Small caps ### + +To write small caps, you can use an HTML span tag: + + Small caps + +(The semicolon is optional and there may be space after the +colon.) This will work in all output formats that support small caps. + +Math +---- + +#### Extension: `tex_math_dollars` #### + +Anything between two `$` characters will be treated as TeX math. The +opening `$` must have a non-space character immediately to its right, +while the closing `$` must have a non-space character immediately to its +left, and must not be followed immediately by a digit. Thus, +`$20,000 and $30,000` won't parse as math. If for some reason +you need to enclose text in literal `$` characters, backslash-escape +them and they won't be treated as math delimiters. + +TeX math will be printed in all output formats. How it is rendered +depends on the output format: + +Markdown, LaTeX, Emacs Org mode, ConTeXt, ZimWiki + ~ It will appear verbatim between `$` characters. + +reStructuredText + ~ It will be rendered using an [interpreted text role `:math:`]. + +AsciiDoc + ~ It will be rendered as `latexmath:[...]`. + +Texinfo + ~ It will be rendered inside a `@math` command. + +groff man + ~ It will be rendered verbatim without `$`'s. + +MediaWiki, DokuWiki + ~ It will be rendered inside `` tags. + +Textile + ~ It will be rendered inside `` tags. + +RTF, OpenDocument, ODT + ~ It will be rendered, if possible, using unicode characters, + and will otherwise appear verbatim. + +DocBook + ~ If the `--mathml` flag is used, it will be rendered using MathML + in an `inlineequation` or `informalequation` tag. Otherwise it + will be rendered, if possible, using unicode characters. + +Docx + ~ It will be rendered using OMML math markup. + +FictionBook2 + ~ If the `--webtex` option is used, formulas are rendered as images + using CodeCogs or other compatible web service, downloaded + and embedded in the e-book. Otherwise, they will appear verbatim. + +HTML, Slidy, DZSlides, S5, EPUB + ~ The way math is rendered in HTML will depend on the + command-line options selected: + + 1. The default is to render TeX math as far as possible using unicode + characters, as with RTF, DocBook, and OpenDocument output. Formulas + are put inside a `span` with `class="math"`, so that they may be + styled differently from the surrounding text if needed. + + 2. If the `--latexmathml` option is used, TeX math will be displayed + between `$` or `$$` characters and put in `` tags with class `LaTeX`. + The [LaTeXMathML] script will be used to render it as formulas. + (This trick does not work in all browsers, but it works in Firefox. + In browsers that do not support LaTeXMathML, TeX math will appear + verbatim between `$` characters.) + + 3. If the `--jsmath` option is used, TeX math will be put inside + `` tags (for inline math) or `
` tags (for display math) + with class `math`. The [jsMath] script will be used to render + it. + + 4. If the `--mimetex` option is used, the [mimeTeX] CGI script will + be called to generate images for each TeX formula. This should + work in all browsers. The `--mimetex` option takes an optional URL + as argument. If no URL is specified, it will be assumed that the + mimeTeX CGI script is at `/cgi-bin/mimetex.cgi`. + + 5. If the `--gladtex` option is used, TeX formulas will be enclosed + in `` tags in the HTML output. The resulting `htex` file may then + be processed by [gladTeX], which will produce image files for each + formula and an HTML file with links to these images. So, the + procedure is: + + pandoc -s --gladtex myfile.txt -o myfile.htex + gladtex -d myfile-images myfile.htex + # produces myfile.html and images in myfile-images + + 6. If the `--webtex` option is used, TeX formulas will be converted + to `` tags that link to an external script that converts + formulas to images. The formula will be URL-encoded and concatenated + with the URL provided. If no URL is specified, the CodeCogs + will be used (`https://latex.codecogs.com/png.latex?`). + + 7. If the `--mathjax` option is used, TeX math will be displayed + between `\(...\)` (for inline math) or `\[...\]` (for display + math) and put in `` tags with class `math`. + The [MathJax] script will be used to render it as formulas. + +[interpreted text role `:math:`]: http://docutils.sourceforge.net/docs/ref/rst/roles.html#math + +Raw HTML +-------- + +#### Extension: `raw_html` #### + +Markdown allows you to insert raw HTML (or DocBook) anywhere in a document +(except verbatim contexts, where `<`, `>`, and `&` are interpreted +literally). (Technically this is not an extension, since standard +Markdown allows it, but it has been made an extension so that it can +be disabled if desired.) + +The raw HTML is passed through unchanged in HTML, S5, Slidy, Slideous, +DZSlides, EPUB, Markdown, Emacs Org mode, and Textile output, and suppressed +in other formats. + +#### Extension: `markdown_in_html_blocks` #### + +Standard Markdown allows you to include HTML "blocks": blocks +of HTML between balanced tags that are separated from the surrounding text +with blank lines, and start and end at the left margin. Within +these blocks, everything is interpreted as HTML, not Markdown; +so (for example), `*` does not signify emphasis. + +Pandoc behaves this way when the `markdown_strict` format is used; but +by default, pandoc interprets material between HTML block tags as Markdown. +Thus, for example, pandoc will turn + + + + + + +
*one*[a link](http://google.com)
+ +into + + + + + + +
onea link
+ +whereas `Markdown.pl` will preserve it as is. + +There is one exception to this rule: text between `