Is there a 'native' way to include your own HTML, CSS and Javascript page in an Antora generated site?
Including an HTML file in the Asciidoc source with inline CSS styling works for only HTML and CSS like this (see the attached image for the result):
++++
include::partial$test.html[]
++++
However, if you were to separate the CSS out and add Javascript then the .css and .js files do not get published since they are not directly included anywhere and the included HTML follows the styling defined by the UI bundle.
Manually copying the CSS and Javascript files to the right place in the build files works as expected (the Antora page is styled and runs the .js as expected)
I would think most Antora documentation is the product of some CI/CD pipeline so you could probably add the CSS and Javascript to the build files as part of the pipeline but that is a messy solution.
What is really required is a way to force Antora to publish some 'extra' files or folders.
I get that the whole point of Antora is to make consistently styled and formatted documentation. The reason for wanting to do this is to include interactive graphs generated by Plotly or Bokeh in the documentation.
It also opens up the possibility of including any kind of interactive window, such as a button to play music. In my case I want to have an 'interactive chord book' that plays and highlights the notes in music chords.
Inline Styling on Antora Site
Your sample pass-through block works because the included file is inserted into the content flow at that position. The test.html file is not, itself, published, but its contents exist within the file using the include macro.
Similarly, if you used this partial block:
++++
include::partial$test.js[]
++++
The contents of test.js are injected into the content flow at that point. test.js itself doesn't need to be published if you are simply embedding a few lines of code.
If you do need test.js to be published, you have three choices:
Store test.js in the module's attachments folder (instead of partials. The partials folder is intended to contain "small" Asciidoc documents that are used multiple times). You'd need to include::attachment$test.js[], but that file does get copied to the build folder.
Use supplemental_files: https://docs.antora.org/antora/latest/playbook/ui-supplemental-files/
Supplemental files allow you to customize the assets in the UI.
Fork the UI and add your customizations directly.
The latter two approaches would be preferable. Currently, Antora only publishes HTML. In the future, publishing to other output formats may occur, including to PDF. PDFs won't work well with embedded HTML, CSS, or JavaScript, so the UI customization is the preferred approach. (PDF generation will likely have a distinct theme support, similar to asciidoctor-pdf).
Related
Is it possible to create a single html page containing embedded D3js charts, CommonMark text, and equations (e.g. Katex or MathJax) and have it all rendered the browser offline?
Must have:
Works offline using modern Firefox/Chrome/Safari, after having
downloaded a minimal number of JavaScript libs.
No requirement for installing anything beyond the web browser. So no local http server, Pandoc, R, Python etc.
Should have:
Possible to write everything in a single html file, which opens in a normal modern browser.
Good archival properties with minimal maintanence.
Motivation:
We work in a high security locked down IT environment and can’t install stuff, but we do have decent web browsers and can run javascript in them.
We routinely share small analytical reports internally, and are experimenting with delivering a directory containing
an html file (with embedded JSON data), and
downloaded D3 and Underscore librariess
All the internal customer has to do is click on index.html. So far this has been very succesful, but we'd like to use markdown and equations too.
We are vaguely aware of data science workbook solutions like Jupyter and Observable, but not sure that these meet our criteria.
Clarification
I know we can download libs and place them in a dir alongside index.html, but I'm not sure if a JavaScript library exists which can render the markdown and equations and write the results directly into the DOM. And even if such a library exists, where in index.html would the markdown be written? Is there some kind of html tag which can just hide a load of raw text which will be parsed by JS?
To answer your question, it is possible. You'll either need Node app that will render static HTML pages or simple HTML page with embedded Javascript. Since all these libraries are available as UDM packages, I suggest 2nd option.
CommonMark CDN: https://cdnjs.com/libraries/commonmark
KaTeX CDN: https://khan.github.io/KaTeX/docs/browser.html
You'll only need to download these libraries and include them in page. KaTeX includes JS to convert simple text to rendered mathematical equation, you only need to give it text and element where to render equation: https://khan.github.io/KaTeX/docs/api.html. CommonMark is similar but it only gives you rendered HTML, you need to insert it with element.innerHTML yourself: https://www.npmjs.com/package/commonmark.
I am starting to build a website from scratch using python, django, and bootstrap. I have noticed that many times js, css, img. and fonts are stored in a folder vendor, such as:
/static/js/vendor/bootstrap/bootstrap.min.js
/static/css/vendor/bootstrap/bootstrap.min.css
or something similar.
What is the benefit of this folder structure over something like:
/static/bootstrap/js/bootstrap.min.js
/static/bootstrap/css/bootstrap.min.css
In the first example, when using the vendor folder as I have often seen, I would have to download bootstrap and unpack the downloaded folder into the js and css vendor sub-directories. In the second example, I can download bootstrap and drop the downloaded folder into /static without having to unpack anything.
It clearly marks which files are third-party libraries that should not be edited directly.
The vendor folder is where you usually (I'm using the word 'usually' because it's not exactly a rule but more of a preference in the coding community with the purpose of having a semantic directory structure) keep third-party resources(icons, images, codes, you name it) as opposed to a lib (library) folder where you or the author of the site/application to be specific keep your original codes in.
So if I were to download and use the site/application in the hypothetical scenario above, I can then create relevant folders for each data type (src/images for images, style/css for css, script/js for js, etc) and move required assets from the lib folder to the new folders without having to edit the third-party codes (or other assets) thus making it easier to rollback on any changes made that cause errors and such.
I have common asp.net mvc project.
I have there one module that contains handlebars templates, javascript modules and stylesheets.
This module is used into different pages and placed somewhere inside div tag.
The new requirement is to use this module into other solution. But I do not want just copy and paste all files related to the module (js, html, css) because it would be hard to maintenance it into different solutions.
So, my question is in what way I should organize this module to be declared only once and to be used into different solutions.
I've had the same requirement before and this is how I dealt with it:
Move your shared content
In my solution, I added a new Shared folder and created a Shared project. You don't necessarily have to move into a new project, I just did this because the shared project also included shared MVC logic.
Add linked shared files to the solutions
It's important to know that this step is optional, it's just that it helps developers in that the files are still in the expected place. Now that you have for example: Project1, Project2 and Shared. Now in Project1 (for example), add your files back in individually. But follow these steps:
Right click the folder you wish to add the file to
Hover over Add then select Existing Item
Navigate to the file in the Shared project and select the file
Before clicking 'Add`, notice the arrow
Click this, and select Add as Link
The benefit of this is that when you click on the file in your solution explorer within Project2, it will open the file in Shared.
Add pre-build events
In each project using the Shared files you will need to add Pre Build Events. Currently, although the project contains a reference to the shared file, it won't actually do anything when you run the project. The solution to this is build events:
Right click your project and select Properties
Select Build Events in the menu
In the Pre-build event command line section enter the following:
xcopy /R /E /Y "$(SolutionDir)SharedProject\Scripts" "$(ProjectDir)Scripts"
To explain: this will copy the contents of your scripts directory in your shared project, and add it to (or replace) your current projects scripts directory. You will need to add a line for each folder (e.g. HTML, CSS, etc)
I understand a couple questions (i.e. this) of this nature have already been posted, however no solid solution has been found. From what it seems, Meteor currently lacks of the ability to dynamically load/render different UI JavaScript (i.e. uilang) or CSS files per template. In my application, I have templates that require specific JS libraries and CSS as oppose to other templates.
For example:
user.html requires -> uilang.js, user_ui_code.js, userstyle.css
admin.html requires -> uilang.js, admin_ui_code.js, admin_style.css
I would need each js/css file to render/load depending on which route gets requested (i.e. example.com/user or example.com/admin), for things like different background-colors, transitions, etc. Meteor documentation states:
Files in /public are served to the client as-is. Use this to store assets such as images. For example, if you have an image located at /public/background.png, you can include it in your HTML with or in your CSS with background-image: url(/background.png). Note that /public is not part of the image URL.
So you would think that putting all your js/css/images assets in public and calling the needed files statically in head would solve the problem. Instead, it seems that the JS (CSS as well) files get concatenated and it all runs at the same time regardless of which route you are on, thus overlapping code. I'm not sure if I am missing something blatantly obvious or is this an actual issue in Meteor?
Thanks for any help.
Meteor doesn't yet support lazy/on demand loading of resources. The feature is on the roadmap as "incremental loading".
In the meantime, have a look at numtel:publicsources and numtel:privatesources, which let you create bundles for lazy loading resources, with or without authentication.
In continuation with the below post is there any way to take ahead the build.xml and add all the plugins such as table, save etc and compress it with the same build.xml file. Reason is to have one ant script file to compress all the files into one, not only the tinymce js files but also other project related files.
tinymce build script to compress all js files
I know the compressio is possible by declaring additional tinyMCE_GZ.init but why use two methods of the compression in same project. It would nice to have as described in above post using build.xml.
How does the plugin structure works it is possible to take everything in one file & still intantiate plugin, right now when I take out all the script tag from table plugin (i.e from table.htm) file I get javascript error even though the script tag is available into the parent html file from which table plugin is invoked..
I tried that, but i failed. I won't say it is impossible, but it will be pretty difficult to achieve. What i ended up doing is to use two compessing methods.