Skip to content

Commit bf2ee4c

Browse files
metonymmetonym
authored
Merge pull request #49 from posthtml/feature-content-attr
feat: add transformPath option to transform matching attribute values
2 parents 4e5df00 + a64f475 commit bf2ee4c

20 files changed

Lines changed: 379 additions & 268 deletions

‎README.md‎

Lines changed: 25 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -29,23 +29,23 @@ npm i -D posthtml-hash
2929

3030
### Input
3131

32-
By default, the plugin will attempt to hash file names that contain `[hash]`. As a qualifier, only nodes with a `href` or `src` attribute are considered.
32+
By default, the plugin will attempt to hash file names that contain `[hash]`. As an additional qualifier, only nodes containing `href`, `src`, or `content` attributes are eligible.
3333

3434
```html
3535
<html>
3636
<head>
37-
<!-- not hashed -->
38-
<link rel="stylesheet" href="reset.css" />
39-
4037
<!-- hashed -->
4138
<link rel="stylesheet" href="style.[hash].css" />
39+
40+
<!-- not hashed -->
41+
<link rel="stylesheet" href="reset.css" />
4242
</head>
4343
<body>
44-
<!-- not hashed -->
45-
<script src="analytics.js"></script>
46-
4744
<!-- hashed -->
4845
<script src="src.[hash].js"></script>
46+
47+
<!-- not hashed -->
48+
<script src="analytics.js"></script>
4949
</body>
5050
</html>
5151
```
@@ -85,7 +85,7 @@ For convenience, you can add the post-build script to your package.json. The `po
8585

8686
Customize the hash length by specifying an integer after the `hash:{NUMBER}`. The default hash length is `20`.
8787

88-
**Note**: This only works for a pattern that uses square brackets and a colon separator. Use the `hashLength` option for other use cases.
88+
**Note**: This only works for a pattern that uses square brackets and a colon separator. Use the `hashLength` option for different patterns.
8989

9090
```html
9191
<script src="src.[hash].js"></script>
@@ -102,19 +102,28 @@ This plugin assumes that the file to process is in the same directory as the Pos
102102
```js
103103
hash({
104104
/**
105-
* Relative path to processed HTML file
105+
* Relative path to the HTML file being processed
106+
* @default ""
106107
*/
107-
path: "public", // default: ""
108+
path: "public",
108109

109110
/**
110111
* File name pattern (regular expression) to match
112+
* @default new RegExp(/\[hash.*]/g)
111113
*/
112-
pattern: new RegExp(/\custom-file-pattern/), // default: new RegExp(/\[hash.*]/g)
114+
pattern: new RegExp(/custom-file-pattern/),
113115

114116
/**
115-
* Custom hash length
117+
* Hash length
118+
* @default 20
116119
*/
117-
hashLength: 8, // default: 20
120+
hashLength: 8,
121+
122+
/**
123+
* Transform the href/src/content attribute value to a relative file path
124+
* @default (filepath) => filepath
125+
*/
126+
transformPath: (filepath) => filepath.replace("https://example.com/", ""),
118127
});
119128
```
120129

@@ -136,7 +145,9 @@ Result:
136145
+ <script src="script.b0dcc67f.js"></script>
137146
```
138147

139-
## [Examples](examples)
148+
## Examples
149+
150+
See the [examples folder](examples) for end-to-end use cases.
140151

141152
## Contributing
142153

‎examples/README.md‎

Lines changed: 0 additions & 3 deletions
This file was deleted.

‎examples/custom-hash/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# examples/basic
1+
# examples/custom-hash
22

33
> Basic usage of the [posthtml-hash](../..) plugin.
44

‎examples/transform-path/.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
/node_modules

‎examples/transform-path/README.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# examples/transform-path
2+
3+
> Basic usage of the [posthtml-hash](../..) plugin.
4+
5+
The assets in the [original/](original) folder contains unprocessed assets for reference; they are not directly manipulated in this example. The corresponding output is the [processed/](processed) folder.
6+
7+
## Use case
8+
9+
This example illustrates hashing images that retain a remote origin URL. A common use case is [Open Graph tags](https://ogp.me/), where the meta `og:image` value must include a remote origin (i.e. "https://example.com").
10+
11+
The sample images are from [placeholder.com](https://placeholder.com/).
12+
13+
## Script
14+
15+
The [script.js](script.js) file contains the script that runs posthtml.
16+
17+
```js
18+
// script.js
19+
const fs = require("fs");
20+
const posthtml = require("posthtml");
21+
const { hash } = require("posthtml-hash");
22+
23+
const html = fs.readFileSync("./processed/index.html");
24+
25+
posthtml()
26+
.use(
27+
hash({
28+
path: "processed",
29+
hashLength: 6,
30+
transformPath: (filepath) => {
31+
// removes the targeted remote origin URL when looking up the files locally
32+
return filepath.replace("https://example.com/", "");
33+
},
34+
})
35+
)
36+
.process(html)
37+
.then((result) => fs.writeFileSync("./processed/index.html", result.html));
38+
```
39+
40+
## Running Locally
41+
42+
Clone the repo and install the dependencies:
43+
44+
```bash
45+
git clone git@github.com:posthtml/posthtml-hash.git
46+
cd posthtml-hash/examples/basic
47+
yarn install
48+
```
49+
50+
Run the script:
51+
52+
```bash
53+
yarn hash
54+
```
55+
56+
To restore the processed folder to its unprocessed state, run:
57+
58+
```bash
59+
yarn clean
60+
```

‎examples/transform-path/clean.js‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
const fs = require("fs-extra");
2+
3+
fs.removeSync("processed");
4+
fs.copySync("original", "processed");

‎examples/transform-path/original/assets/small-image.[hash].png‎

737 Bytes
Loading

‎examples/transform-path/original/image.[hash].png‎

1.22 KB
Loading

‎examples/transform-path/original/index.html‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="utf-8" />
5+
<meta property="og:image" content="https://example.com/image.[hash].png" />
6+
<meta property="twitter:image" content="https://example.com/assets/small-image.[hash].png" />
7+
</head>
8+
<body></body>
9+
</html>

‎examples/transform-path/package.json‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{
2+
"name": "transform-path",
3+
"version": "1.0.0",
4+
"main": "script.js",
5+
"private": true,
6+
"scripts": {
7+
"clean": "node clean.js",
8+
"hash": "node script.js"
9+
},
10+
"devDependencies": {
11+
"fs-extra": "^9.0.1",
12+
"posthtml": "^0.15.0",
13+
"posthtml-hash": "../../"
14+
}
15+
}

0 commit comments

Comments
 (0)