I'm using a slightly modified version of the example generator from Jekyll's plugins section of their docs (https://github.com/mojombo/jekyll/wiki/Plugins#generators) and I'm curious if there is any way to parse a liquid/markdown file instead of a plain HTML files from the example?
Notice this line:
self.read_yaml(File.join(base, '_layouts'), 'category_index.html')
That category index.html file is the target file which will be used in generated files. My goal is to be able to pass an object to a my generator from my _config file which I can then use to build a bunch of pages from a .markdown file instead. Does anyone know if this is possible or have any recommendations for achieving this? I looked into the Kramdown lib that's used to parse markdown internally, and I'm not opposed to invoking it myself if I have to, just wasn't sure if I was going deeper than I needed to for something that should be so simple. The API for the Page object which my generator creates is here: http://ruby-doc.org/gems/docs/j/jekyll-0.12.0/Jekyll/Page.html
Thanks a ton,
- Keith
You can generate virtually any format you want, from virtually any data source you want, in a generator, because you're writing straight Ruby with full access to the Jekyll object model. For example, here's a generator I put together the other night that fetches GitHub commits during jekyll build.
The question I would be asking is this:
Do I need a plugin to accomplish this?
If so, do I need a formal generator plugin as discussed in the Jekyll docs?
Or should I subclass, monkey-patch, or otherwise change the behavior of the built-in generator?
Also, the differences between Markdown and HTML files in this context (where you control 100% of what gets generated) are mostly nominal. read_yaml IIRC will actually read the front matter from both, so that shouldn't be an issue.
Related
Before I run off the in wrong direction, if adding a new output format to Sphinx, might one have to add special case code to all existing Sphinx extensions?
For example I see that the 'todo' extension seems to try and use admonitions but has to have special case latex code - might I have to do similar for every extension that someone might use unless I can do some similar jiggery-pokery to reuse existing formatting features?
All extensions that make use of Sphinx's add_node() function need to be adjusted to cover the new output format. Otherwise, your new output format builder will not be able to process the custom nodes. You still should be able to build, though.
However, let me clarify the following:
Not all extensions make use of add_node().
In many cases, you should be able to register an already existing function for the new output format, just like in the example of the extension development tutorial in the Sphinx documentation.
You should be able to override the add_node() registrations of the extensions you use without modifying the source code of the extensions by re-registering the nodes at the end of your project's conf.py file.
I have lot of documentation written in AsciiDoc and correctly separated into folders. I use asciidoctor with a custom CSS to render my docs to HTML. The problem with this is that it generates a single HTML page that is very long. I was surfing the web and found that the atom docs are also written in AsciiDoc, but these docs have not all the information together, in fact they are separated into different sections.
Here the atom docs: https://atom.io/docs/v0.201.0/getting-started-why-atom
I want to know if there is a tool that can generate this, a flag or a specific syntax.
I think it is not really user friendly to have all the info in one long single page.
I have a site where the static content is generated using the asciidoctor-jekyll plugin and jekyll.
I had also plugged the java version of asciidoctor to generate views with the play framework at some point but decided that I prefer that the content I generate with asciidoctor to be static and delivered by a CDN.
EDIT:
Also, GitBookIO supports asciidoctor.
I've found this post Jekyll, modify the way some html tags are rendered
Which does explain how to extend redcarpet itself.
But what else needs to be done in order to get such extension to work?
What name does the extension correspond to in the _config.yml ?
Do I need to include anything in my gem file?
If I simply change "markdown: redcarpet" to "markdown: RedcarpetMod" github pages will send a main telling me that there were syntax errors in the first markdown file it tries to process.
Your stumbling block here is GitHub pages — the answer given by #cyrusza in the question you've linked works fine (I am using it to modify redcarpet's rendering on one of my sites). GitHub pages, however, runs in safe mode which means that it does not allow custom plugins at all and instead only supports a few specific plugins.
Check the Plugins page in the Jekyll documentation for the note about safe mode (in the first blue box), and the GitHub Pages help page about plugins for the list of which plugins are allowed.
Ruby has a few good document generators like Yard, rDoc, even Glyph. The thing is that Sphinx does websites, PDF's, epub, LaTex...etc. It does all these things in restructuredtext.
Is there an alternative to this in the Ruby world? Maybe a combination of programs? If I could use Markdown as well that would be even better.
Since version 1.0, Sphinx has had a concept of "domains" which are ways of marking up code entities (like method calls, objects, functions, whatever) from lannguages other than Python and/or C.
There is a ruby domain, so you could just use Sphinx itself. The only thing you would be missing (I think) is Sphinx's ability to create documentation from source automatically using the autodoc extension, which works specifically on Python code.
If you want to use Markdown, you might check out JDoc, which is a very simple, Ruby-based documentation framework that lets you use widely-supported markup and put it under source control. It lets you edit the documentation in your text editor of choice, and it supports:
Markdown or Textile
syntax highlighting
easy internal links
a hierarchical documentation structure (useful for large projects)
customizable styling and structure (but it looks nice out of the box, too)
It generates static HTML, so the resulting documentation is easy to host and doesn't have much of an impact on your server load.
To see it in action, check out wpmvc.org.
Another couple of options would be to use Middleman which is a static site generator that accepts either Kramdown or Markdown as input.
There are also frameworks that are designed specifically for technical documentation that use Middleman (both of which are on GitHub) including lord/slate and pnerger/dpslate (the later is a fork of the former and provides some enhancements that were not appropriate for pulling). The Slate format provides a format for documentation that includes many of the features of Sphinx with some additional enhancements. It features a three-pane view of a document which includes an automatically generated Table of Contents, a Main center body, and then sample code panel to the right. Like Sphinx the sample code has syntax highlighting.
I'm a newbie to SugarCRM development. In my project, I have to generate a pdf for one entity details(say Account details). On details page, I have added "Print PDF" button, upon clicking this button I have one independent script (I mean to say that it was not implemented as per Sugar framework). In this script we are querying database for the required details and building one html string. Using html2pdf library, converting this html string to pdf.
I dont know whether it is an efficient implementation or not, but everything is working fine as per the requirement. But we have one problem when the original string contains some special characters like currency symbols of different countries. We are getting the html fine, but in pdf getting question marks (?) for those special characters.
While trying to fix this issue, when I looked into SugarCRM code, I found some pdf classed inside includes/ directory that creating an impression that Sugar itself has some built-in library to generate pdf's. Is it true?
If that is true, will it solve my problem, i.e. displaying different countries currency symbols in pdf.
Can anybody please help me to in resolving this. Thanks in advance.
-Venkat Nehatha
Venkat, SugarCRM does indeed have its own pdf generation ability. We use it to generate customer orders, quotes, invoices, and statements.
Though I've done some work on the pdf generation myself, I don't think I'm really experienced enough to be able to guide someone else in detail in the use of Sugar's pdf capabilities. I can tell you that we use pdf generation only in our own custom modules, so the files are found in [sugarRoot]/modules/[customModule]/. (You may know that unless you know exactly what you're doing, NEVER modify the main SugarCRM files in the [root]/modules/ folder!) In the previously mentioned custom module folder are two sub-folders, "sugarpdf", which has the code that accesses the modules/database to get the information to write to the pdf, and a "tpls" folder that holds the layout information for the header, body, and footer of the pdf, in HTML format, using the information from the sugarpdf folder's file.
I strongly recommend you visit the SugarCRM developer forums where you will be in touch with many developers much more experienced than me in Sugar.
I hope this helps in some way.