I use pandoc in VSCode to generate HTML files from Markdown files.
I use the following htmlOptString in VSCode:
"pandoc.htmlOptString": "-s -f gfm -t html5 --template=pandoc-template.html"
I don't want to have to change that line every time I render a document.
I do not understand how I can use metadata to pass information like author, title or more, from the MD file.
For example the following does not create the $title$ variable:
---
title: test
...
In my template the title element id rendered as empty
<title>$title$</title>
How do I create variables from the markdown file?
I also tried using a YAML metadata file to no effect.
UPDATE
Environment
MacOS Sierra
Pandoc 2.1.1
Latest VSCode
I tried specifying the yaml_metadata_block extension in the pandoc command
My new htmlOptString is:
"pandoc.htmlOptString": "-s --from=gfm+yaml_metadata_block -t html5 --template=pandoc-template.html"
When I run the command from a terminal the result is the same, i.e. the title block is rendered in HTML and no $title$ variable is generated.
Pandoc added support for this in version 2.13 (released on 2021-03-21). Nowadays, it should be enough to update to the latest version for this to work.
Related
GitHub supports asciidoc readme files, but it looks like "include" is not supported.
I want to use doctoolchain which can render and export to html and pdf (and maybe into other formats). This tool works great.
I could use raw.githack.com to show the generated html file from the GitHub repository.
But I think it would be a good idea to have the result also as one (1) readme.adoc file.
How to export into one (1) asciidoc file, which I could use as it is as readme file so that github will render it and show? Best would be to use doctoolchain, when this tool will render my documentation it could also generate the one-file-asciidoc-documentation.
I think internally asciidoctor collects and merge all these "include" files. So maybe this file is already available in any place? The doctoolchain build folder contains only the target files.
You are right there is a long dicussion why includeis not supported by github.
You can achieve your goal with doctoolChain and pandoc(https://pandoc.org/). Following steps are required:
configure your docDir/Config.groovy
inputFiles should have docbook defined
inputFiles = [[file: 'yourfile', formats['docbook']]]
run the doctoolchain task generateDocbook - it creates ???.xml file somewhere in docDir/build
generate from the generated docbook again an asciidoctor file - `pandoc <FILENAME_OF_GENERATED_DOCBOOK.XML> -f docbook -t asciidoctor -o <FILENAME_OF_ASCIIDOCTOR_WHICH_HAS_EVERYTHING>
make sure it runs automatically and you commit it regulary
now you are ready
This script can be used to resolve includes and to generate one (1) output file:
https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/scripts/asciidoc-coalescer.rb
some information about the script and possible next steps you can read here:
AsciiDoc Backend (AsciiDoc 2 AsciiDoc) for preprocessing
to use it, ruby and asciidoc must be installed:
asciidoctor.org/#installation
I have written the documentation for a medium sized C++ piece of software using Doxygen together with Markdown. I am quite happy with it, as after changing the xml layer I ended up with something like that:
http://docs.mitk.org/nightly/index.html
I would like to bring this documentation online, ideally using something like ReadtheDocs, where the documentation would be automatically built after a "git commit", and hosted to be browsed.
ReadtheDocs looks like the ideal site but uses Sphinx and reStructuredText as defaults. Doxygen can be used too, but AFAIK only through Breathe. Going through that route essentially means that I would need to re-structure all the documentation if I don't want to dump all the API documentation into a single page (http://librelist.com/browser//breathe/2011/8/6/fwd-guidance-for-usage-breathe-with-existing-doxygen-set-up-on-a-large-project/#cab3f36b1e4bb2294e2507acad71775f).
Paradoxically, Doxygen is installed in the read-the-docs server, but after struggling I could not find a workaround to skip its Sphinx or Mkdocs.
I've tried the following solution to use Doxygen on Read The Docs and it seems to work:
set up empty sphinx project (refer to official sphinx doc),
in sphinx conf.py add command to build doxygen documentation,
use conf.py html_extra_path config directive to overwrite generated doxygen documentation over generated sphinx documentation.
I've tested this with following source tree:
.../doc/Doxyfile
/build/html
/sphinx/conf.py
/sphinx/index.rst
/sphinx/...
Some explanation:
in my setup doxygen generates its documentation in "doc/build/html",
ReadTheDocs runs its commands in directory where it finds conf.py file.
What to do:
add following lines in conf.py to generate doxygen docs:
import subprocess
subprocess.call('cd .. ; doxygen', shell=True)
update conf.py html_extra_path directive to:
html_extra_path = ['../build/html']
In this configuration ReadTheDocs should properly generate and store Doxygen html documentation.
todo:
other documentation formats, for example: pdf.
This answer builds upon the great one already given by "kzeslaf". So follow the steps described by him first, before you continue here.
While his answer works as intended, I had the problem that ReadTheDocs (RTD) uses a rather old version of Doxygen (1.8.13 at the time of writing). This caused several issues for me like the one reported here. Additionally, if you set up Doxygen to treat warnings as errors, you might need to override this option on RTD due to version-related warnings.
I found a simple solution to upgrade the Doxygen version on RTD using conda.
Create an environment.yml file somewhere in your project (probably in the documentation directory). The content is as follows:
name: RTD
channels:
- conda-forge
- defaults
dependencies:
- python=3.8
- doxygen=<VERSION>
Replace <VERSION> with any version number that you like to use and that is available on conda-forge. Use conda search doxygen -c conda-forge to get a list of all available versions or simply check this site. You can also remove =<VERSION> and conda should install the latest one automatically.
Now you need to create an RTD config file if you haven't done this already. Add the following lines:
conda:
environment: <DIRECTORY>/environment.yml
Replace <DIRECTORY> with the actual location of the environment.yml file (relative to your project root, for example: docs/environment.yml). Now, if you followed all the steps in the answer of "kzelaf" and the ones I mentioned, RTD should successfully build your Doxygen documentation with the version you selected. You can check it in the lower right corner of the created pages. Alternatively, add subprocess.run(["doxygen", "-v"]) to your conf.py and check the RTD build logs.
I would love to use tags inside Emacs, like Vim does. However, I have some problems to set it ## Setup:
GNU Emacs GUI version 25.0.5.1 (x86_64-w64-mingw32)
Compiled from Harroogan Emacs.
Projectile and Helm, using the latest version of Projectile/Helm from MELPA
Exuberant Ctags binary 58 for Windows
Windows 7 x64 bit.
Actions:
The binary ctags.exe is in the PATH, and respons when I call it from command line in Windows with ctags --help.
I tried various things to create a TAGS file, without any result. One thing that I seem to have results, is with the help of the package projectile. But it gives me weird results.
When I'm inside a project, currently the buffer index.php is being opened. Inside that buffer, I regenate tags file with projectile-regenate-tags, with C-c p R.
The messages buffer gives me the following:
Starting a new list of tags tables
Making tags-file-name local to Dev/digiloket3/TAGS while let-bound!
I see the file TAGS is being created in the project root.
The directory root structure is like this:
index.php
.projectile
|- INCLUDE
|- AJAX
|- SCRIPTS
|- PHP
Issue:
Then I visit the tag list with find-tag (g C-]). When I notice I don't get all variables and class/functions that are defined in the project.
When I call the helm-etags-select, I see the directory/file next to the tag. And what confuses me, is that only functions/classes and variables from files in the directory AJAX are being visible in the tag list, and not the variables/classes/functions from the files in the directory PHP.
Then I manually creating the TAGS file with in the command prompt with the right directory on ctags -R.
With no help.
All files in the folder PHP are called ****.inc.
When I renamed one of the files to ****.php, then they're popping up in my ctags table.
So the real issue here is how I could tell projectile/ctags to recognize .inc files as PHP-files, or index it
But I'm also open for another things to create a TAGS table on Windows platform with the ctags available on command line.
Any suggestion?
man ctags for starters (if you can do so in Windows? There is documentation available in any case.)
Assigning file extensions for a language is done with --langmap. Run the following command to see how that argument works:
ctags --langmap=php:+.inc.foo.bar --list-maps=php
So in your case, you would probably use something like this to generate your TAGS file:
ctags -e -R --langmap=php:+.inc
Tangentially, note also the options listed when you run ctags --list-kinds=php. You can then control which of those will be used: ctags --php-kinds=-v-j --list-kinds=php
Is there a way to create a README.md file for GitHub that compiles from other .md files? For instance, let's say I have three files: repo/1.md, repo/2.md, and repo/3.md. I want to combine the files in this order to create repo/README.md.
This SO question gives some help, but it's more than 2 years old and I'm thinking (hoping) there might be new ideas out there now. One answer suggests using Pandoc to compile .md files into outputting to html:
pandoc *.md > markdown_book.html
I tried this with my files. My .md files take the form:
# Page 1
testing
Once in repo/, I ran:
pandoc *.md > README.html
which created:
<h1 id="page-1">Page 1</h1>
<p>testing # Page 2 testing # Page 3 testing</p>
This is not looking right, but I went ahead and ran the following to get back to a .md file:
pandoc -o README.md README.html
which produced:
Page 1
======
testing \# Page 2 testing \# Page 3 testing
I expected:
# Page 1
testing
# Page 2
testing
# Page 3
testing
So to wrap up:
Is Pandoc the best tool for the job, or is there an easier approach to combining .md files together? The Marked app has syntax for including external files, <<[path/file], but I don't think there is an option to "export" the compiled document to .md.
If not, what is the right way to do this with Pandoc? I'd like to combine markdown files without having to go to another format first.
Pandoc 1.11.1 works for me on Ubuntu, going straight from Markdown to Markdown, although it converts # headings into underlined headings:
pandoc -o README.md 1.md 2.md 3.md
Make sure your files include a final newline in each of your source files; omitting this is the only way that I was able to reproduce your error.
I'd like to know whether there is a way to change the default tool to generate message sequence charts (msc) of Doxygen. Actual default tool for Doxygen is the mscgen (http://www.mcternan.me.uk/mscgen/) and it's a good tool, but I'd like to use msc-gen (https://sites.google.com/site/mscgen2393/) that seems to be a more complete tool.
I've already tried to create a link at "MSCGEN_PATH = /usr/bin/" to the msc-gen (like ln -s /usr/bin/msc-gen ./mscgen) but command line of tools are different. There is a specific way to configure Doxygen to "learn" this new tool command line?
For the current msc-gen version (v4.0.0), your solution should work.
I just tried setting the MSCGEN_PATH to the msc-gen installation directory and it worked for me. msc-gen already brings a copy of its main executable with the name mscgen.exe to be called by doxygen.
This solution is also described in the second paragraph of:
http://msc-generator.sourceforge.net/help/4.0/
You may also like to have a look at Plant UML and its doxygen integration:
http://plantuml.com/index.html
http://plantuml.com/doxygen.html