Skip to content

Commit 3548a20

Browse files
nex3nex3
committed
Add a specialized README for npm
1 parent 18a1539 commit 3548a20

File tree

3 files changed

+137
-3
lines changed

3 files changed

+137
-3
lines changed

‎package/README.npm.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
A pure JavaScript implementation of [Sass][sass]. **Sass makes CSS fun again**.
2+
3+
<table>
4+
<tr>
5+
<td>
6+
<img width="118px" alt="Sass logo" src="https://rawgit.com/sass/sass-site/master/source/assets/img/logos/logo.svg" />
7+
</td>
8+
<td valign="middle">
9+
<a href="https://www.npmjs.com/package/sass"><img width="100%" alt="npm statistics" src="https://nodei.co/npm/sass.png?downloads=true"></a>
10+
</td>
11+
<td valign="middle">
12+
<a href="https://travis-ci.org/sass/dart-sass"><img alt="Travis build status" src="https://api.travis-ci.org/sass/dart-sass.svg"></a>
13+
<br>
14+
<a href="https://ci.appveyor.com/project/nex3/dart-sass"><img alt="Appveyor build status" src="https://ci.appveyor.com/api/projects/status/84rl9hvu8uoecgef?svg=true"></a>
15+
</td>
16+
</tr>
17+
</table>
18+
19+
[sass]: http://sass-lang.com/
20+
21+
This package is a distribution of [Dart Sass][], compiled to pure JavaScript
22+
with no native code or external dependencies. It provides a command-line `sass`
23+
executable and a Node.js API.
24+
25+
[Dart Sass]: https://github.com/sass/dart-sass
26+
27+
* [Usage](#usage)
28+
* [API](#api)
29+
* [See Also](#see-also)
30+
* [Behavioral Differences from Ruby Sass](#behavioral-differences-from-ruby-sass)
31+
32+
## Usage
33+
34+
You can install Sass globally using `npm install -g sass` which will provide
35+
access to the `sass` executable. You can also add it to your project using
36+
`npm install --save-dev sass`. This provides the executable as well as a
37+
library:
38+
39+
[npm]: https://www.npmjs.com/package/sass
40+
41+
```js
42+
var sass = require('sass');
43+
44+
sass.render({file: scss_filename}, function(err, result) { /* ... */ });
45+
46+
// OR
47+
48+
var result = sass.renderSync({file: scss_filename});
49+
```
50+
51+
[See below](#api) for details on Dart Sass's JavaScript API.
52+
53+
## API
54+
55+
<!-- #include ../README.md "JavaScript API" -->
56+
57+
## See Also
58+
59+
* [Dart Sass][], from which this package is compiled, can be used either as a
60+
stand-alone executable or as a Dart library. Running Dart Sass on the Dart VM
61+
is substantially faster than running the pure JavaScript version, so this may
62+
be appropriate for performance-sensitive applications. The Dart API is also
63+
(currently) more user-friendly than the JavaScript API. See
64+
[the Dart Sass README][Using Dart Sass] for details on how to use it.
65+
66+
* [Node Sass][], which is a wrapper around [LibSass][], the C++ implementation
67+
of Sass. Node Sass supports the same API as this package and is also faster
68+
(although it's usually a little slower than Dart Sass). However, it requires a
69+
native library which may be difficult to install, and it's generally slower to
70+
add features and fix bugs.
71+
72+
[Using Dart Sass]: https://github.com/sass/dart-sass#using-dart-sass
73+
[Node Sass]: https://www.npmjs.com/package/node-sass
74+
[LibSass]: https://sass-lang.com/libsass
75+
76+
## Behavioral Differences from Ruby Sass
77+
78+
<!-- #include ../README.md "Behavioral Differences from Ruby Sass" -->

‎package/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "sass",
3-
"description": "A Dart implementation of Sass, compiled to JS.",
3+
"description": "A pure JavaScript implementation of Sass.",
44
"license": "MIT",
55
"bugs": "https://github.com/sass/dart-sass/issues",
66
"homepage": "https://github.com/sass/dart-sass",

‎tool/grind.dart‎

Lines changed: 58 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,13 @@ import 'dart:convert';
77
import 'dart:io';
88

99
import 'package:archive/archive.dart';
10+
import 'package:charcode/charcode.dart';
1011
import 'package:collection/collection.dart';
1112
import 'package:grinder/grinder.dart';
1213
import 'package:http/http.dart' as http;
1314
import 'package:node_preamble/preamble.dart' as preamble;
1415
import 'package:pub_semver/pub_semver.dart';
16+
import 'package:source_span/source_span.dart';
1517
import 'package:xml/xml.dart' as xml;
1618
import 'package:yaml/yaml.dart';
1719

@@ -127,12 +129,66 @@ void _writeNpmPackage(String destination, Map<String, dynamic> json) {
127129
dir.createSync(recursive: true);
128130

129131
log("copying package/package.json to $destination");
130-
new File(p.join(dir.path, 'package.json'))
132+
new File(p.join(destination, 'package.json'))
131133
.writeAsStringSync(JSON.encode(json));
132134

133135
copy(new File(p.join('package', 'sass.js')), dir);
134136
copy(new File(p.join('build', 'sass.dart.js')), dir);
135-
copy(new File('README.md'), dir);
137+
138+
log("copying package/README.npm.md to $destination");
139+
new File(p.join(destination, 'README.md'))
140+
.writeAsStringSync(_readAndResolveMarkdown('package/README.npm.md'));
141+
}
142+
143+
final _readAndResolveRegExp = new RegExp(
144+
r"^<!-- +#include +([^\s]+) +"
145+
'"([^"\n]+)"'
146+
r" +-->$",
147+
multiLine: true);
148+
149+
/// Reads a Markdown file from [path] and resolves include directives.
150+
///
151+
/// Include directives have the syntax `"<!-- #include" PATH HEADER "-->"`,
152+
/// which must appear on its own line. PATH is a relative file: URL to another
153+
/// Markdown file, and HEADER is the name of a header in that file whose
154+
/// contents should be included as-is.
155+
String _readAndResolveMarkdown(String path) => new File(path)
156+
.readAsStringSync()
157+
.replaceAllMapped(_readAndResolveRegExp, (match) {
158+
String included;
159+
try {
160+
included = new File(p.join(p.dirname(path), p.fromUri(match[1])))
161+
.readAsStringSync();
162+
} catch (error) {
163+
_matchError(match, error.toString(), url: p.toUri(path));
164+
}
165+
166+
Match headerMatch;
167+
try {
168+
headerMatch = "# ${match[2]}\n".allMatches(included).first;
169+
} on StateError {
170+
_matchError(match, "Could not find header.", url: p.toUri(path));
171+
}
172+
173+
var headerLevel = 0;
174+
var index = headerMatch.start;
175+
while (index >= 0 && included.codeUnitAt(index) == $hash) {
176+
headerLevel++;
177+
index--;
178+
}
179+
180+
// The section goes until the next header of the same level, or the end
181+
// of the document.
182+
var sectionEnd = included.indexOf("#" * headerLevel, headerMatch.end);
183+
if (sectionEnd == -1) sectionEnd = included.length;
184+
185+
return included.substring(headerMatch.end, sectionEnd).trim();
186+
});
187+
188+
/// Throws a nice [SourceSpanException] associated with [match].
189+
void _matchError(Match match, String message, {url}) {
190+
var file = new SourceFile.fromString(match.input, url: url);
191+
throw new SourceSpanException(message, file.span(match.start, match.end));
136192
}
137193

138194
@Task('Build a Chocolatey package.')

0 commit comments

Comments
 (0)