search

asciidoctor / asciidoctor.js

:scroll: A JavaScript port of Asciidoctor, a modern implementation of AsciiDoc
https://asciidoctor.org
MIT License
730 stars 135 forks source link

When using Node.js, the default stylesheet should be resolved to the local bundled css file #478

Open ggrossetie opened 6 years ago

ggrossetie commented 6 years ago

Currently the default path is ./asciidoctor.css. On a browser I don't really know what the value should be... ideas ?

ggrossetie commented 5 years ago

To be more specific, consider the following code:

require('asciidoctor.js')().convertFile('file.adoc', {'header_footer': true, 'to_file': false})

Output:

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 1.5.7.1">
<title>Hello</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700">
<link rel="stylesheet" href="./asciidoctor.css">
</head>
<body class="article">
<div id="header">
<h1>Hello</h1>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p><strong>This</strong> is Asciidoctor</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_section_1">Section 1</h2>
<div class="sectionbody">
<div class="paragraph">
<p>blo</p>
</div>
</div>
</div>
</div>
<div id="footer">
<div id="footer-text">
Last updated 2018-07-08 14:42:27 CEST
</div>
</div>
</body>
</html>

Arguably ./asciidoctor.css could be a good default value since we don't know where the file will be written. In other words we don't know for sure if ./node_modules/asciidoctor.js/dist/asciidoctor.css will be resolved...

Having said that, if the user do the following:

$ npm install asciidoctor.js

convert.js

require('asciidoctor.js')().convertFile('file.adoc', {'header_footer': true})

file.adoc

= Document

*This* is Asciidoctor

== Section 1
node convert.js

Then using ./node_modules/asciidoctor.js/dist/asciidoctor.css is better than ./asciidoctor.css

ggrossetie commented 5 years ago

Instead of using a relative path we could use an absolute path __dirname + /node_modules/asciidoctor.js/dist/asciidoctor.css

ggrossetie commented 5 years ago

Maybe it's just a documentation issue see https://github.com/asciidoctor/asciidoctor.js/issues/457

@mojavelinux Do you have an opinion on this issue ? My goal is to provide a better out of the box experience for newcomers.

mojavelinux commented 5 years ago

The way core handles this is that it copies the stylesheet to the location it references. It doesn't assume the stylesheet is just there (unless you set !copycss). Of course, in a browser environment, it's not going to be able to copy the file. That's why I'd argue that linking to the location closest to the document is the best default. Either the user needs to put it there, or the processor can put it there (if possible). But that way, the default always ends up being consistent.