VSinerva/freesewing
1
0
Fork 0
Code Activity

chore: Added docs for jargon

Browse source
This commit is contained in:
Joost De Cock 2019-10-12 16:12:33 +02:00
parent bc46cc9f1b
commit 07b659ef8f
10 changed files with 302 additions and 22 deletions
Download patch file Download diff file Expand all files Collapse all files

146
packages/gatsby-remark-jargon/README.md
View file

@ -1,7 +1,7 @@
<p align="center">
<a title="Go to freesewing.org" href="https://freesewing.org/"><img src="https://freesewing.org/img/logo/black.svg" align="center" width="150px" alt="Freesewing logo"/></a>
<a title="Go to freesewing.org" href="https://freesewing.org/"><img src="https://freesewing.org/logo.svg" align="center" width="150px" alt="FreeSewing logo"/></a>
<br>
<a href="https://freesewing.org/">FreeSewing v2</a>
<a href="https://freesewing.org/">FreeSewing</a>
</p>
<p align="center">An open source platform for made-to-measure sewing patterns</p>
<p align='center'><a
@ -50,25 +50,155 @@
A gatsby-transformer-remark sub-plugin for jargon terms
## About
This wraps the [remark-jargon](https://github.com/freesewing/freesewing/tree/develop/packages/remark-jargon) plugin
for Gatsby so you can use _jargon_ in the markdown/mdx of your Gatsby site:
![An example of this plugin being used on freesewing.org](example.png)
## Install
```bash
npm install --save gatsby-remark-jargon
```
## Configuration
In `gatsby-config.js` include your jargon file, and add the remark plugin:
```js
{
resolve: 'gatsby-remark-jargon',
options: { jargon: require('./jargon.js') }
}
```
## Usage
### The jargon file
The jagon file is a simple key-value file:
```js
const jargon = {
msf: "<b>MSF</b> Médecins Sans Frontières / Doctors Without Borders — An international, independent, medical humanitarian organisation. See <a href='https://www.msf.org/'>msf.org</a>"
}
export default jargon
```
### Using jargon in markdown
This plugin will only add markup to your jargon if you emphasize it. In the following example,
only the first mention of MSF will be changed:
```md
_MSF_ was founded in 1971 by 13 doctors and journalists. Today, MSF is a worldwide movement of more than 67,000 people.
```
This will be rendered as:
```html
<p>
<em>
<span class="jargon-term">
MSF
<span class="jargon-info">
<b>MSF</b> Médecins Sans Frontières / Doctors Without Borders — An international, independent, medical humanitarian organisation. See <a href='https://www.msf.org/'>msf.org</a>
</span>
</span>
</em>
was founded in 1971 by 13 doctors and journalists. Today, MSF is a worldwide movement of more than 67,000 people.
</p>
```
Which you can then style so that the definition is only show on hover/touch.
### Styling your jargon
You will need to add CSS to style your jargon properly, and hide the definition by default.
Below is an example to get you started:
```css
// Add a dashed line under jargon terms
.jargon-term {
text-decoration: underline dotted #228be6
}
// Add a question mark behind/above jargon terms
.jargon-term::after {
content: "?";
font-weight: bold;
display: inline-block;
transform: translate(0, -0.5em);
font-size: 75%;
color: #228be6;
margin-left: 3px;
}
// Hover behavior for the therm itself
.jargon-term:hover {
position: relative;
text-decoration: none;
cursor: help;
}
// Hide info by default
.jargon-term .jargon-info {
display: none
}
// Show info on hover
.jargon-term:hover .jargon-info {
display: block;
position: absolute;
top: 1.5em;
left: 0;
background: #F8F8F8;
border: 1px solid #DCDCDC;
padding: 1rem;
border-radius: 4px;
font-size: 90%;
min-width: 250px;
max-width: 450px;
z-index: 1;
}
```
## Tips for using jargon
### Lowercase your terms in the jargon file
When looking for terms to match, we lowercase the term your emphazised.
So in the jargon file, you should use `msf`, but in your text, you can use `MSF`, `Msf`, or `msf`.
### If you use HTML, only use inline elements
Your jargon term definition can contain HTML, but only inline elements.
Typically, you will want to stick to:
- Making things **bold**
- Inserting [links](#)
## About FreeSewing 🤔
Where the world of makers and developers collide, that's where you'll find FreeSewing.
Our [core library](https://freesewing.dev/en/freesewing) is a *batteries-included* toolbox
Our [core library](https://freesewing.dev/) is a *batteries-included* toolbox
for parametric design of sewing patterns. It's a modular system (check our list
of [plugins](https://freesewing.dev/en/plugins) and getting started is as simple as:
of [plugins](https://freesewing.dev/plugins) and getting started is as simple as:
```bash
npm init freesewing-pattern
```
The [getting started] section on [freesewing.dev](https://freesewing.dev/) is a good
The [getting started](https://freesewing.dev/start) section on [freesewing.dev](https://freesewing.dev/) is a good
entrypoint to our documentation, but you'll find a lot more there, including
our [API documentation](https://freesewing.dev/en/freesewing/api),
as well as [examples](https://freesewing.dev/en/freesewing/examples),
and [best practices](https://freesewing.dev/en/do).
our [API reference](https://freesewing.dev/api),
as well as [our turorial](https://freesewing.dev/tutorial),
and [best practices](https://freesewing.dev/do).
If you're a maker, checkout [freesewing.org](https://freesewing/) where you can generate
our sewing patterns adapted to your measurements.

BIN
packages/gatsby-remark-jargon/example.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 56 KiB

130
packages/gatsby-remark-jargon/info.md Normal file
View file

@ -0,0 +1,130 @@
## About
This wraps the [remark-jargon](https://github.com/freesewing/freesewing/tree/develop/packages/remark-jargon) plugin
for Gatsby so you can use _jargon_ in the markdown/mdx of your Gatsby site:
![An example of this plugin being used on freesewing.org](example.png)
## Install
```bash
npm install --save gatsby-remark-jargon
```
## Configuration
In `gatsby-config.js` include your jargon file, and add the remark plugin:
```js
{
resolve: 'gatsby-remark-jargon',
options: { jargon: require('./jargon.js') }
}
```
## Usage
### The jargon file
The jagon file is a simple key-value file:
```js
const jargon = {
msf: "<b>MSF</b> Médecins Sans Frontières / Doctors Without Borders — An international, independent, medical humanitarian organisation. See <a href='https://www.msf.org/'>msf.org</a>"
}
export default jargon
```
### Using jargon in markdown
This plugin will only add markup to your jargon if you emphasize it. In the following example,
only the first mention of MSF will be changed:
```md
_MSF_ was founded in 1971 by 13 doctors and journalists. Today, MSF is a worldwide movement of more than 67,000 people.
```
This will be rendered as:
```html
<p>
<em>
<span class="jargon-term">
MSF
<span class="jargon-info">
<b>MSF</b> Médecins Sans Frontières / Doctors Without Borders — An international, independent, medical humanitarian organisation. See <a href='https://www.msf.org/'>msf.org</a>
</span>
</span>
</em>
was founded in 1971 by 13 doctors and journalists. Today, MSF is a worldwide movement of more than 67,000 people.
</p>
```
Which you can then style so that the definition is only show on hover/touch.
### Styling your jargon
You will need to add CSS to style your jargon properly, and hide the definition by default.
Below is an example to get you started:
```css
// Add a dashed line under jargon terms
.jargon-term {
text-decoration: underline dotted #228be6
}
// Add a question mark behind/above jargon terms
.jargon-term::after {
content: "?";
font-weight: bold;
display: inline-block;
transform: translate(0, -0.5em);
font-size: 75%;
color: #228be6;
margin-left: 3px;
}
// Hover behavior for the therm itself
.jargon-term:hover {
position: relative;
text-decoration: none;
cursor: help;
}
// Hide info by default
.jargon-term .jargon-info {
display: none
}
// Show info on hover
.jargon-term:hover .jargon-info {
display: block;
position: absolute;
top: 1.5em;
left: 0;
background: #F8F8F8;
border: 1px solid #DCDCDC;
padding: 1rem;
border-radius: 4px;
font-size: 90%;
min-width: 250px;
max-width: 450px;
z-index: 1;
}
```
## Tips for using jargon
### Lowercase your terms in the jargon file
When looking for terms to match, we lowercase the term your emphazised.
So in the jargon file, you should use `msf`, but in your text, you can use `MSF`, `Msf`, or `msf`.
### If you use HTML, only use inline elements
Your jargon term definition can contain HTML, but only inline elements.
Typically, you will want to stick to:
- Making things **bold**
- Inserting [links](#)

6
packages/gatsby-remark-jargon/package.json
View file

@ -1,6 +1,6 @@
{
"name": "gatsby-remark-jargon",
"version": "2.1.0",
"version": "2.1.1-beta.0",
"description": "A gatsby-transformer-remark sub-plugin for jargon terms",
"author": "Joost De Cock <joost@decock.org> (https://github.com/joostdecock)",
"homepage": "https://freesewing.org/",
@ -31,7 +31,7 @@
},
"peerDependencies": {},
"dependencies": {
"remark-jargon": "^2.1.0"
"remark-jargon": "^2.1.1-beta.0"
},
"devDependencies": {},
"files": [
@ -41,7 +41,7 @@
],
"publishConfig": {
"access": "public",
"tag": "latest"
"tag": "next"
},
"engines": {
"node": ">=8.0.0",

1
packages/gatsby-remark-jargon/rollup.config.js
View file

@ -23,6 +23,7 @@ if (typeof module !== 'undefined')
export default {
input: 'src/index.js',
output,
external: ['remark-jargon'],
plugins: [
peerDepsExternal(),
resolve(),

25
packages/remark-jargon/README.md
View file

@ -1,7 +1,7 @@
<p align="center">
<a title="Go to freesewing.org" href="https://freesewing.org/"><img src="https://freesewing.org/img/logo/black.svg" align="center" width="150px" alt="Freesewing logo"/></a>
<a title="Go to freesewing.org" href="https://freesewing.org/"><img src="https://freesewing.org/logo.svg" align="center" width="150px" alt="FreeSewing logo"/></a>
<br>
<a href="https://freesewing.org/">FreeSewing v2</a>
<a href="https://freesewing.org/">FreeSewing</a>
</p>
<p align="center">An open source platform for made-to-measure sewing patterns</p>
<p align='center'><a
@ -50,25 +50,34 @@
A Remark plugin for jargon terms
## About
This [Remark](https://remark.js.org/) plugin allows you to use _jargon_ in your
markdown/mdx content and use a centrally managed file of jargon terms and their definitions.
![An example of this plugin being used on freesewing.org](example.png)
Please see [gatsby-remark-jargon](https://github.com/freesewing/freesewing/tree/develop/packages/gatsby-remark-jargon) for
more info and instructions.
## About FreeSewing 🤔
Where the world of makers and developers collide, that's where you'll find FreeSewing.
Our [core library](https://freesewing.dev/en/freesewing) is a *batteries-included* toolbox
Our [core library](https://freesewing.dev/) is a *batteries-included* toolbox
for parametric design of sewing patterns. It's a modular system (check our list
of [plugins](https://freesewing.dev/en/plugins) and getting started is as simple as:
of [plugins](https://freesewing.dev/plugins) and getting started is as simple as:
```bash
npm init freesewing-pattern
```
The [getting started] section on [freesewing.dev](https://freesewing.dev/) is a good
The [getting started](https://freesewing.dev/start) section on [freesewing.dev](https://freesewing.dev/) is a good
entrypoint to our documentation, but you'll find a lot more there, including
our [API documentation](https://freesewing.dev/en/freesewing/api),
as well as [examples](https://freesewing.dev/en/freesewing/examples),
and [best practices](https://freesewing.dev/en/do).
our [API reference](https://freesewing.dev/api),
as well as [our turorial](https://freesewing.dev/tutorial),
and [best practices](https://freesewing.dev/do).
If you're a maker, checkout [freesewing.org](https://freesewing/) where you can generate
our sewing patterns adapted to your measurements.

BIN
packages/remark-jargon/example.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 56 KiB

9
packages/remark-jargon/info.md Normal file
View file

@ -0,0 +1,9 @@
## About
This [Remark](https://remark.js.org/) plugin allows you to use _jargon_ in your
markdown/mdx content and use a centrally managed file of jargon terms and their definitions.
![An example of this plugin being used on freesewing.org](example.png)
Please see [gatsby-remark-jargon](https://github.com/freesewing/freesewing/tree/develop/packages/gatsby-remark-jargon) for
more info and instructions.

4
packages/remark-jargon/package.json
View file

@ -1,6 +1,6 @@
{
"name": "remark-jargon",
"version": "2.1.0",
"version": "2.1.1-beta.0",
"description": "A Remark plugin for jargon terms",
"author": "Joost De Cock <joost@decock.org> (https://github.com/joostdecock)",
"homepage": "https://freesewing.org/",
@ -44,7 +44,7 @@
],
"publishConfig": {
"access": "public",
"tag": "latest"
"tag": "next"
},
"engines": {
"node": ">=8.0.0",

3
packages/remark-jargon/src/index.js
View file

@ -22,6 +22,7 @@ export default options => {
let html = options.jargon[term.toLowerCase()]
let value = `<span class="jargon-term">${term}<span class="jargon-info">${html}</span></span>`
let position = node.children[0].position
console.log('is jargon', { term, html, value, position })
position.end.column = position.end.column + value.length - term.lenght
position.end.offset = position.end.column - 1
node.children = [
@ -32,7 +33,7 @@ export default options => {
indent: node.children[0].indent
}
]
}
} else console.log('-', node)
}
const transform = tree => {