Code Monkey home page Code Monkey logo

asciidoctor-skins's Introduction

asciidoctor-skins: CSS stylesheets for asciidoctor

Markdown is superbly simple. Perfect for writing quick notes and pages with a basic structure. Asciidoctor is superbly sophisticated. Where markdown fails, asciidoc/asciidoctor allows you to document things with ease, fine grain control and a civilised demeanor, worlds away from hair wrenching word processors.

Asciidoctor comes with a very clean default stylesheet that saves users from spending time formatting their documents. This repository is for users who would like some other style choices, without having to rewrite stylesheets from scratch. All stylesheets in here pull in asciidoctor’s defaults first and then apply custom styles to a few elements.

Usage

If you have no idea what asciidoctor is, check out their fabulous project here.

Once you’ve got an .adoc document going, download the asciidoctor.css file and a css skin file of your choice into your project directory.
  1. In your .adoc file, add the following line: :stylesheet: Your_Chosen_Stylesheet.css

  2. Render your html file by running asciidoctor sample.adoc

  3. Et voilà! Your beautiful web page based document is rendered.

Demo

You can preview all of the stylesheets in the online demo.

To change the displayed stylesheet, just add the name of the CSS file after a ? character at the end of the URL. For example, to preview the material stylsheet, just add ?material.

Custom preview

You can now add a JS switcher to any document to quickly preview the contents rendered with any of the available asciidoctor skins. Just add the following line to the <body> section of any asciidoctor-generated HTML page:

<script src="https://darshandsoni.com/asciidoctor-skins/switcher.js" type="text/javascript"></script>

Skins

Note: To preview all of them, visit the screenshots page.

Available stylesheets:

📎
the template skin is specifically designed as an aid for theming experiments, to make it easier to see the sections of the document affected by different CSS classes.

Additional themes

Bookmarklet

You can quickly and easily test out how different themes look with a given document using the asciidoctor-skins bookmarklet. This will add a dropdown menu at the top of the page with all the different available themes. Just paste the following code into your address bar to create a CSS switcher for any Asciidoctor-generated document:

javascript:(function()%7Bvar%20body%20%3D%20document.getElementsByTagName('body')%5B0%5D%3Bscript%20%3D%20document.createElement('script')%3Bscript.type%3D%20'text%2Fjavascript'%3Bscript.src%3D%20'https%3A%2F%2Fdarshandsoni.com%2Fasciidoctor-skins%2Fswitcher.js'%3Bbody.appendChild(script)%7D)()

Alternatively, just drag the link on the demo page to your browser’s bookmark bar.

Boomarklet generated by the Bookmarklet Creator. Thanks to markdown-css for the idea!

Contribution

The purpose of this project is to allow asciidoc/asciidoctor users greater flexibility when it comes to customizing the look and feel of their documentation. Apart from the available stylesheets, you are welcome to build your own. If you think the world could use it, submit a pull request and it will be featured too! You can either edit template.css (which has most elements listed), or create your own stylesheets from scratch.

Licence Agreement

By contributing changes to this repository, you agree to license your contributions under the MIT license. This ensures your contributions have the same license as the project and that the community is free to use your contributions. You also assert that you are the original author of the work that you are contributing unless otherwise stated.

Credits

License

MIT.

asciidoctor-skins's People

Contributors

darshandsoni avatar dohliam avatar glopinous avatar jfernandz avatar subraizada3 avatar ubcigen avatar yanwenkun avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

asciidoctor-skins's Issues

Nesting dropdown for 'navbar' skin

captur-nav
For style that use a 'navbar' skin such as boot-flatly it would be great to see the (first) nesting hierarchy as a dropdown

Is this easy to achieve or should I use navbar for this ?

Cheers

Using the switcher.js makes syntax highlightning from highlight.js disappear.

When using the switcher.js as described (for example, here as a passthrough in the asciidoc)

//skin selector for HTML backend
++++

<script src="https://darshandsoni.com/asciidoctor-skins/switcher.js" type="text/javascript"></script>

++++

highlighter.js does not work anymore after a skin has been changed, only the first time. As Highlight.js is one of the supported syntax colourings for asciidoctor, it would be great if the switcher and highlight.js could work together seamslessly.

By having a quick look I think that all that needs do be done in switcher.js would be to make a check if there exits a hljs object and if so just call hljs.initHighlightning() again

Do not link against the stylesheet on asciidoctor.org

The stylesheet on asciidoctor.org is not the official default stylesheet for Asciidoctor. Please don't link against it. That stylesheet has extra styles that are required for the website to function. It's also not kept in sync with the stylesheet shipped with Asciidoctor and may move when the website is redesigned.

Instead, you can use the following URL to retrieve the default stylesheet for the latest release directly from the GitHub repository:

https://cdn.jsdelivr.net/gh/asciidoctor/[email protected]/data/stylesheets/asciidoctor-default.css

If you want to link against the development version instead, you can use this URL:

https://cdn.jsdelivr.net/gh/asciidoctor/asciidoctor@master/data/stylesheets/asciidoctor-default.css

Syntaxhighlight in Dark theme doesn't work

I love the dark theme, but syntax highlight has major issues.

This code produces the below results:

[source,python]
----
def x(a, b):
  return a + b
----

[source,bash]
----
$ ls gocode
 bin   pkg

$ ll gocode
drwxr-xr-x a a 4.0 KB Thu Mar  3 05:52:00 2022  bin
drwxr-xr-x a a 4.0 KB Thu Mar  3 05:45:43 2022  pkg
----

[source,javascript]
----
function square(number) {
  return number * number;
}
----

Here is highlight.js:
adoc-highlight js

Here is coderay:
adoc-coderay

Here is pygments:
adoc-pygments

Here is rouge:
adoc-rouge

I tried altering the dark.css, but i couldn't get to change anything. Following is the relevant code in dark.css:

code{color:var(--linkcoloralternate);background-color: var(--sidebarbackground) !important}

.literalblock pre, .listingblock pre:not(.highlight), .listingblock pre[class="highlight"], .listingblock pre[class^="highlight "], .listingblock pre.CodeRay, .listingblock pre.prettyprint {
  background: var(--sidebarbackground);
  color: var(--white);
}

Now, how to fix/alter/customize source/literal block css in the theme dark?

We really need some documentation for the themes. If there is already, i apologise that i couldn't find it.

I would greatly appreciate anyone pointing out if i'm making any mistake and/or help fix this issue.

Thanks!

Failed to load resource

I noticed the error below on loading the skins:

Failed to load resource: the server responded with a status of 404 (Not Found) => http://darshandsoni.com/asciidoctor-skins/css/css/asciidoctor.css

It seems that this is occurring because of this line that tries to import asciidoctor.css from css/asciidoctor.css, which of course doesn't exist now since the skins themselves are located in the css directory.

I'll see if I can submit a PR to fix this.

asciidoctor / adoc-foundation .toc-root font setting

I'm using asciidoctor.css together with adoc-foundation.css and I've added a custom font everywhere except for code blocks. However, I've noticed that the element .toc-root (the title of the document at the top of the table of contents) is defined nowhere in any of the css files and therefore has retained the original font (wherever that was defined then, since apparently it also didn't inherit this setting from anywhere that I've changed the settings).

Could a setting for .toc-root maybe be added to the stylesheets? Thanks! :)

Dark style is not rendered as expected

I'm trying to use the dark.css style but it is not rendered as espected. I'm getting this in vscode

Captura de pantalla_2019-11-20_15-19-05

and this one in Chrome after render the .adoc to an .html with asciidoctor

Captura de pantalla_2019-11-20_15-21-17

I was expecting something like this

Captura de pantalla_2019-11-20_15-23-33

I guess it is happening the same for other styles.

[QUESTION] Style for html mail

hi
I am wondering if any of styles are more adapted to generate HTML content that can be used as MAIL body.
The default HTML5 code generated is excellent on a modern browser but is rendering poorly when in a mail client (gmail, outlook, mac mail) and i am note sure how to adapt it.

tx

Requesting 'classic' theme emulating the look of asciidoc

It would be desirable to be able to migrate documentation from asciidoc to asciidoctor while preserving the styling, and then make separate consideration of whether to change it.

Can we please have an "asciidoc" or "classic" theme that emulates, as possible, the original asciidoc style?

asciidoctor.css Unexpected missing generic font family in stylesheet

We are using the asciidoctor.css stylesheet we found in your project to help with the vscode-didact project (https://github.com/redhat-developer/vscode-didact) and while working through some issues reported by SonarCloud, I received the error: Unexpected missing generic font family

on this line:

.verseblock pre{font-family:"Open Sans","DejaVu Sans",sans;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility}

.verseblock pre{font-family:"Open Sans","DejaVu Sans",sans;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility}

Here's a bit more about the issue: https://rules.sonarsource.com/css/RSPEC-4649

It appears that 'sans' is not a globally accepted font name, but 'sans-serif' is.

Replace demo with Asciidoctor-based sample article

The current demo page is based on the html5-test-page project. It does a good job of demonstrating most of the elements included in HTML5, but it is missing many Asciidoctor-specific features such as admonitions. To give a better sense of how the themes look when applied to .adoc files, the demo should be replaced with an Asciidoctor-based sample article.

Code background-color overwritten

When using source highlighter like highlightjs, background-color property for code tag is not displayed properly (by this I mean, it does not use highlightjs styles), because of this line ((snippet below is taken from fedora theme))
code{color:var(--white);background-color: var(--highlightcolor) !important}

I suggest changing it to something similar to how it is defined in asciidoctor.css
:not(pre)>code{color:var(--white);background-color: var(--highlightcolor)}

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.