I use org.asciidoctor.convert plugin for gradle to generate API documentation for my team. I include files:
include::{snippets}/index/curl-request.adoc[]
and want to place it's content into spoiler or anything like that. Is there any way to somehow hide dynamicaly asciidoc elements? I try to use
pass:[<details open>
include::{snippets}/index/curl-request.adoc[]
</details>]
but it is not processed include inside it. Any ideas will be higly appreciated. Without hiding snippets my documentation have almost unlimited scrol :). If no such way with ascii doc, suggestions of other documentation formats, where i can include files content and place it into the spoiler is also appreciated.
As this was so helpful for me - I added here the solution from Robin's comment.
No CSS and Javascript needed!
Here is an example:
+++ <details><summary> +++
Check `reference.conf`:
+++ </summary><div> +++
----
play {
http {
secret.key = asdf
secret.key = ${?SECRET_KEY}
...
}
...
}
----
+++ </div></details> +++
This creates a collapsed element:
..and this expanded image:
Update
As Foad's answer looks more elegant, I tried his proposed solution for a ReDoc Markup with no success.
As Guillaume Grossetie has mentioned here
Using passthrough to include raw HTML is not recommended because now your document is tightly coupled with the output.
and it is deprecated. The new syntax for collapsible/foldable sections is
.some description
[%collapsible]
====
this
is
going
to be
folded
====
This is a late answer but maybe it will help you/others.
The following asciidoc features are the key for implementing dynamic showing/hiding of blocks:
If your output is only HTML then you can embed any HTML in the document using
++++ any HTML contents ++++
This includes
<style> tags containing custom CSS classes
custom HTML tags for show/hide functionality like <input type="checkbox" />
<script> tags containing Javascript code to hide/show some blocks, e.g. by adding event listeners to checkboxes.
As #LightGuard has already mentioned, role attributes are converted to CSS class references. E.g.
[source,role="someCssClass"]
----
...
----
is converted to something like
<div class="someCssClass">
</div>
So you can reference this CSS class from Javascript code and implement show/hide by modifying the display CSS attribute.
For a simple example implementation see https://raw.githubusercontent.com/NorbertSandor/jsinterop.xyz/master/jsinterop-project/jsinterop-website/src/main/asciidoc/index.asciidoc (near the top of the file).
Related
On the main page of every repository in GitHub or BitBucket it shows the Readme.md in a very pretty format.
Is there a way to make the same thing with ruby? I have already found some gems like Redcarpet, but it never looks pretty. I've followed this instructions for Redcarpet.
Edit:
After I tried Github's markup ruby gem, the same thing is happening.
What is shown is this:
And what I want is this:
And I'm sure it's not only css missing, because after 3 backquotes (```) I write the syntax like json or bash and in the first image it is written.
Edit2:
This code here:
renderer = Redcarpet::Render::HTML.new(prettify: true)
markdown = Redcarpet::Markdown.new(renderer, fenced_code_blocks: true)
html = markdown.render(source_text)
'<script src="https://cdn.rawgit.com/google/code-prettify/master/loader/run_prettify.js"></script>'+html
Generated this:
Github provides its own ruby gem to do so: https://github.com/github/markup.
You just need to install the right dependencies and you're good to go.
You need to enable a few nonstandard features.
Fenced code blocks
Fenced code blocks are nonstandard and are not enabled by default on most Markdown parsers (some older ones don't support them at all). According to Redcarpet's docs, you want to enable the fenced_code_blocks extension:
:fenced_code_blocks: parse fenced code blocks, PHP-Markdown style. Blocks delimited with 3 or more ~ or backticks will be considered as code, without the need to be indented. An optional language name may be added at the end of the opening fence for the code block.
Syntax Highlighting
Most Markdown parsers to not do syntax highlighting of code blocks. And those that do always do it as an option. Even then, you will still need to provide your own CSS styles to have the code blocks styled properly. As it turns out, Redcarpet does include support for a prettify option to the HTML renderer:
:prettify: add prettyprint classes to <code> tags for google-code-prettify.
You will need to get the Javascript and CSS from the google-code-prettify project to include in your pages.
Solution
In the end you'll need something like this:
renderer = Redcarpet::Render::HTML.new(prettify: true)
markdown = Redcarpet::Markdown.new(renderer, fenced_code_blocks: true)
html = markdown.render(source_text)
As #yoones said Github shares their way to do it but to be more precise they use the gem "commonmarker" for markdown. Though as far as I can tell this thing does not give the full formatted HTML file but only a piece that you insert into <body>. So you can do it like I did:
require "commonmarker"
puts <<~HEREDOC
<!DOCTYPE html>
<html>
<head>
<style>#{File.read "markdown.css"}</style>
</head>
<body class="markdown-body Box-body">
#{CommonMarker.render_html ARGF.read, %i{ DEFAULT UNSAFE }, %i{ table }}
</body>
</html>
HEREDOC
Where did I get the markdown.css? I just stole the CSS files from an arbitrary Github page with README rendered and applied UNCSS to it -- resulted in a 26kb file, you can find it in the same repo I just linked.
Why the table and UNSAFE? I need this to render an index.html for Github Pages because their markdown renderer can't newlines within table cells, etc. so instead of asking it to render my README.md I make the index.html myself.
How do I render a strikethrough (or line-through) in an adoc file?
Let's presume I want to write "That technology is -c-r-a-p- not perfect."
That technology is [line-through]#crap# not perfect.
As per Ascii Doc manual, [line-through] is deprecated. You can test here.
Comment from Dan Allen
It's important to understand that line-through is just a CSS role. Therefore, it needs support from the stylesheet in order to appear as though it is working.
If I run the following through Asciidoctor (or Asciidoctor.js):
[.line-through]#strike#
I get:
<span class="line-through">strike</span>
The default stylesheet has a rule for this:
.line-through{text-decoration:line-through}
You would need to do the same.
It is possible to customize the HTML that is generated using custom templates (Asciidoctor.js supports Jade templates). In that case, you'd override the template for inline_quoted, check for the line-through role and produce either an <s> or, preferably, a <del> instead of the span.
If you're only targeting the HTML backend, you can insert HTML code verbatim via a passthrough context. This can be done inline by wrapping the parts in +++:
That technology is +++<del>+++crap+++</del>+++ not perfect.
This won't help you for PDF, DocBook XML, or other output formats, though.
If the output is intended for HTML you can pass HTML.
The <s> HTML element renders text with a strikethrough, or a line
through it. Use the element to represent things that are no longer
relevant or no longer accurate.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/s
To render as:
Example text.
use:
1. Pass inline:
Example +++<s>text</s>+++.
2. Pass-through macro:
Example pass:[<s>text</s>].
3. Pass block:
++++
Example <s>text</s>.
++++
How can I programmatically add script or stylesheet tag to a page specified in page's YAML front matter (meta)?
Assuming there is src/documents/posts/a.html.eco with following contents:
---
layout: default
scripts: ['a.js']
---
Blog post that requires a special javascript
and layout src/layouts/default.html.eco with following contents:
...
#getBlock('scripts').toHTML()
</body>
...
The final result for posts/a.html should be:
...
<!-- some extra stuff that was added when processing script tag -->
<script scr="/scripts/a.js"></script>
</body>
...
..while other pages shouldn't have a reference to /scripts/a.js
The comment above tag is just to show that there may be some processing envolved before injecting the tag.
I tried many approaches using different events in docpad.coffee file (including approach taken from docpad-plugin-livereload plugin) but every time I was facing the same problem - script tag was applied to all pages instead of being applied to a.html only. Here is one of my tries:
renderDocument: (opts) ->
{extension,templateData,file,content} = opts
if extension == 'html' and scripts = file.get('scripts')
if typeof scripts != 'undefined'
scripts.forEach (scriptName) ->
#docpad.getBlock('scripts').add('<!-- custom script tag here -->')
I've also tried render event, populateCollections (which is not documented however I found it in docpad-plugin-livereload plugin) and even extendTemplateData events and no luck so far.
I know there is a method of doing this right inside a layout:
#getBlock('scripts').add(#document.scripts or [])
..which is totally fine and it really works as expected however it doesn't seem to provide enough freedom for me to manipulate the content before it's injected to a page.. And even if it's possible I won't like the idea of having some heavy logic inside layout template, I want it to be in a plugin/docpad.coffee
Hopefully that makes sense
Try templateData.getBlock('scripts').add instead of docpad.getBlock('scripts').add
I'm trying to import a code snippet into HTML using doxygen. The code snippet is a few lines long and I've preformatted it using <pre> tags. However, when the HTML is generated, doxygen is inserting
<div class="line">
before each line of my snippet. The result is the HTML is generated with extra space between each line of the code snippets. How do I get rid of this? I just want the code snippet in there with the pre-formatted whitespace.
This is with doxygen 1.8.1.1
I ran into the same problem and reported a bug against DoxyGen. See link: https://bugzilla.gnome.org/show_bug.cgi?id=681135
The answer is quick and simple: The "line" class has been added quite recently and it takes an update of the custom CSS files. In my case the resolution was simple:
Open the project in DoxyWizard
Go to "Expert" view and configure HTML output
Remove the entry for your Custom CSS
run DoxyWizard once
Copy the div.line and div.line.glow definitions from default CSS into your custom CSS and modify as desired
Be happy
HTH, Nick
I'm trying to change the style of a blog post (for instance change the title color), based on the labels associated to the post.
I'm a bit new to the templating, so I though I would be going to add a class with the label in the title <h3> element, and then add my CSS rules.
So I found this which would generate a proper list of labels separated by a space:
<b:loop values='data:post.labels' var='label'><data:label.name/> </b:loop>
However, it seems the validator does not let me add this inside the class attribute as follow:
<h3 class='post-title entry-title <b:loop values="data:post.labels" var="label"><data:label.name/> </b:loop>'>
From there, I found half the solution. Apparently, I should use expr:class instead of class as follow:
<h3 expr:class='"post-title entry-title " + data:list_of_labels'>
So now:
- How can I build this variable data:list_of_labels? (basically how to set a variable)
- Is there a full description of the template syntax somewhere?
- Is there another way to go around this?
Thanks,
JB
This should do it. Using XML entities allows you bypass the XML validation and move the Blogger functions to where you need them. Longer explanation here: http://www.karlhorky.com/2012/06/add-blogger-labels-to-post-as-css.html
<div class="post<b:if cond="data:post.labels"><b:loop values="data:post.labels" var="label"> <data:label.name></data:label.name></b:loop></b:if>">
<data:post.body>
</div>
There is no way to set variables in the blogger data xml, however you can set variables using javascript.
There are many pages on the blogger data xml. Google is your friend. For example this one.
You are on the right track: do a loop, use javascript to check for the combinations you want, change the style properties or load a css file dynamically.