VSinerva/freesewing
1
0
Fork 0
Code Activity

Merge pull request #6091 from freesewing/joost

Browse source 
feat: New jargon functionality
This commit is contained in:
Joost De Cock 2024-02-18 16:21:25 +01:00 • committed by GitHub
commit f516d2deb6
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
12 changed files with 370 additions and 64 deletions
Download patch file Download diff file Expand all files Collapse all files

93
markdown/dev/guides/markdown/jargon/en.md
View file

@ -1,17 +1,49 @@
---
title: Using jargon
order: yyy
---
Jargon are terms that could throw off new users.
Rather than create a glossary on every page, we use a plugin to manage
Rather than create a glossary on every page, we use MDX to manage
jargon terms for us. This page shows you how to use it.
<Tip compact>Think of jargon as glossary terms</Tip>
## Using jargon
## Adding jargon terms
To use jargon, it's sufficient to emphasize the term:
To add a new jargon term, you first need to document it, than you can add it to
the jargon component for the website you'd like to add it to:
| Website | Jargon file | GitHub link |
| ------- | ----------- | ----------- |
| freesewing.dev | `sites/dev/components/jargon.mjs` | [jargon.mjs](https://github.com/freesewing/freesewing/blob/develop/sites/dev/comonents/jargon.mjs) |
| freesewing.org | `sites/org/components/jargon.mjs` | [jargon.mjs](https://github.com/freesewing/freesewing/blob/develop/sites/org/components/jargon.mjs) |
The file holds a `jargon` object that consists of key/value pairs per language.
The **key** is the jargon term. It should always be lowercase because we lowercase the term before matching it.
So in your text, you can use `ESM`, `esm`, or even `eSm`, but the key in the jargon file should be `esm`.
The **value** is the URL path to the documentation page for the term.
You do not need to include the language prefix in the doc path.
Note that this shoud point to a page that holds MDX content.
An example will make this more clear:
```js
const jargon = {
en: {
basting: 'docs/sewing/basting',
},
nl: {
driegen: 'docs/sewing/basting',
},
}
```
## Using jargon terms in MDX content
To use jargon inside MDX content (like the markdown of our documentation, blog
posts, and so on), it's sufficient to emphasize the term:
```md
We are migrating from _cjs_ to _esm_ modules
@ -21,51 +53,14 @@ Which renders as:
We are migrating from _cjs_ to _esm_ modules
## Adding jargon
## Using jargon terms outside MDX content
To add a new jargon term, you need to add it to the jargon file for the
website you'd like to add it to:
Outside MDX content -- more precisely, in React components -- you can achieve the same effect with the `Term` component:
| Website | Jargon file | GitHub link |
| ------- | ----------- | ----------- |
| freesewing.dev | `sites/dev/jargon.mjs` | [jargon.mjs](https://github.com/freesewing/freesewing/blob/develop/sites/dev/jargon.mjs) |
| freesewing.org | `sites/org/jargon.mjs` | [jargon.mjs](https://github.com/freesewing/freesewing/blob/develop/sites/org/jargon.mjs) |
```mjs
import { Term } from 'site/components/jargon.mjs'
The file consists of key/value pairs where:
- The **key** is the jargon term
- The **value** is the jargon description
### Tips for jargon keys
The key in the jargon file should always be lowercase. That's because we
lowercase the term before matching it.
So in your text, you can use `ESM`, `esm`, or even `eSm`, but the key in
the jargon file should be `esm`.
### Tips for jargon values
The value can hold HTML tags, just make sure it's valid HTML and don't go
overboard.
Note that the definition will be _italic_ by default.
## FreeSewing Jargon Glossary
Below is the jargon which is currently defined and available to use
on our websites.
### Jargon on freesewing.dev
| Term | Description |
| ----------- | ----------- |
| `cjs` | **CJS** stands for CommonJS, it is the JavaScript module format popularized by NodeJS, but now increasingly phased out in favor of **ESM**
| `esm` | **ESM** stands for EcmaScript Module, it is the standardized module syntax in JavaScript
### Jargon on freesewing.org
| Term | Description |
| ----------- | ----------- |
_(Currently, no jargon has been defined for the freesewing.org site.)_
export const MyComponent = () => (
<p>Look, it works here too: <Term>esm</Term></p>
)
```

18
markdown/dev/reference/terms/cjs/en.md Normal file
View file

@ -0,0 +1,18 @@
---
title: cjs
---
**cjs** stands for **CommonJS**. It is a module system for JavaScript that was
popularized by NodeJS, and as such typically used in server-side JavaScript.
CommonJS uses the **require** keyword to import modules:
```js
const fs = require('fs')
```
In recent years, **cjs** is increasingly being replaced by **esm**, or ECMA
Script Modules which is the official module system of the JavaScript language,
and the future-proof choice.
Since version 3, FreeSewing is ESM-only.

7
markdown/dev/reference/terms/en.md Normal file
View file

@ -0,0 +1,7 @@
---
title: Terminology
---
These are terms that we use on this website that may or may not be new to you:
<ReadMore />

17
markdown/dev/reference/terms/esm/en.md Normal file
View file

@ -0,0 +1,17 @@
---
title: esm
---
**esm** stands for **ECMAScript Modules** and is the official module system of
the JavaScript language, supported both in the browser, and on the server.
While ESM is the official standard, before it existed people would typically use CJS outside the browser, as it was popularized by NodeJS.
Some libraries still are not available in ESM, but FreeSewing has been ESM-only since version 3.
ESM uses the **import** keyword to import modules:
```js
import fs from 'fs'
```

14
markdown/dev/reference/terms/variadic/en.md Normal file
View file

@ -0,0 +1,14 @@
---
title: Variadic
---
A **variadic** function is a function that accepts a variable number of arguments.
For example, JavaScript's `console.log` method is variadic:
```js
console.log('one')
console.log('one', 'two')
console.log('one', 'two', 'three')
console.log('It', 'works', 'regardless', 'of', 'how', 'many', 'arguments', 'you', 'pass')
```

3
markdown/org/docs/about/site/nl.md
View file

@ -61,7 +61,8 @@ Schakel [Two-Factor Authentication](/account/mfa/) in om je FreeSewing account t
## Maak het je eigen
Now that you have a FreeSewing account, there's more you can do on FreeSewing.org. Click through to learn more about the following features: Click through to learn more about the following features: Click through to learn more about the following features: Click through to learn more about the following features: Click through to learn more about the following features: Click through to learn more about the following features: Click through to learn more about the following features: Click through to learn more about the following features: Klik door voor meer informatie over de volgende functies: Klik door voor meer informatie over de volgende functies: Klik door voor meer informatie over de volgende functies: Klik door voor meer informatie over de volgende functies: Klik door voor meer informatie over de volgende functies: Klik door voor meer informatie over de volgende functies: Klik door voor meer informatie over de volgende functies: Klik door voor meer informatie over de volgende functies: Klik door voor meer informatie over de volgende functies: Klik door voor meer informatie over de volgende functies: Klik door voor meer informatie over de volgende functies: Klik door voor meer informatie over de volgende functies: Klik door voor meer informatie over de volgende functies: Klik door voor meer informatie over de volgende functies: Klik door voor meer informatie over de volgende functies: Klik door voor meer informatie over de volgende functies: Klik door voor meer informatie over de volgende functies: Klik door voor meer informatie over de volgende functies:
Now that you have a FreeSewing account, there's more you can do on FreeSewing.org.
Klik door voor meer informatie over de volgende functies:
- [Account](/docs/about/site/account)
- [Maten sets](/docs/about/site/sets)

25
sites/dev/components/jargon.mjs Normal file
View file

@ -0,0 +1,25 @@
import { Term as SharedTerm } from 'shared/components/jargon.mjs'
/*
* This object holds jargon terminology for FreeSewing.dev
*
* This object holds key/value pairs per language where:
* - key: holds the jargon term (make sure to lowercase it and strip dots)
* - value: holds the path to the documentation page as when browsing the website
*
* To be clear:
* - You need to first create a markdown page explaining the term.
* - Only afterwards can you add it here
* - Since this uses dynamic MDX loaded from GitHub,it won't work until pushed
*/
const jargon = {
en: {
cjs: 'reference/terms/cjs',
esm: 'reference/terms/esm',
},
}
/*
* DO NOT CHANGE ANYTHING BELOW THIS LINE
*/
export const Term = ({ children }) => <SharedTerm {...{ jargon, children }} site="dev" />

191
sites/org/components/jargon.mjs Normal file
View file

@ -0,0 +1,191 @@
import { Term as SharedTerm } from 'shared/components/jargon.mjs'
/*
* This object holds jargon terminology for FreeSewing.dev
*
* This object holds key/value pairs per language where:
* - key: holds the jargon term (make sure to lowercase it and strip dots)
* - value: holds the path to the documentation page as when browsing the website
*
* To be clear:
* - You need to first create a markdown page explaining the term.
* - Only afterwards can you add it here
* - Since this uses dynamic MDX loaded from GitHub,it won't work until pushed
*/
// prettier-ignore
const jargon = {
en: {
'basic sewing supplies': 'docs/sewing/basic-sewing-supplies',
'basting': 'docs/sewing/basting',
'coverlock': 'docs/sewing/coverlock',
'cutting': 'docs/sewing/cutting',
'darts': 'docs/sewing/darts',
'double welt pockets': 'docs/sewing/double-welt-pockets',
'ease': 'docs/sewing/ease',
'edgestitching': 'docs/sewing/edgestitching',
'fabric grain': 'docs/sewing/fabric-grain',
'good sides together': 'docs/sewing/good-sides-together',
'hemming': 'docs/sewing/hemming',
'highpoint shoulder': 'docs/sewing/hps',
'hps': 'docs/sewing/hps',
'jersey': 'docs/sewing/jersey',
'knit binding': 'docs/sewing/knit-binding',
'knit fabric': 'docs/sewing/knit-fabric',
'on the fold': 'docs/sewing/on-the-fold',
'pinning': 'docs/sewing/pinning',
'rayon': 'docs/sewing/rayon',
'sa': 'docs/sewing/seam-allowance',
'seam allowance': 'docs/sewing/seam-allowance',
'serger': 'docs/sewing/serger',
'slipstitch': 'docs/sewing/slipstitch',
'topstitching': 'docs/sewing/topstitching',
'trimming': 'docs/sewing/trimming',
'twin needle': 'docs/sewing/twin-needle',
'zig-zag stitch': 'docs/sewing/zig-zag-stitch',
},
de: {
'abnäher': 'docs/sewing/darts',
'coverlock': 'docs/sewing/coverlock',
'doppelpaspeltaschen': 'docs/sewing/double-welt- pockets',
'fadenlauf': 'docs/sewing/fabric-grain',
'grundlegendes nähzubehör': 'docs/sewing/basic-sewing-supplies',
'gute seiten zusammen': 'docs/sewing/good-sides-together',
'heften': 'docs/sewing/basting',
'hochpunkt schulter': 'docs/sewing/hps',
'hps': 'docs/sewing/hps',
'im stoffbruch': 'docs/sewing/on-the-fold',
'jersey': 'docs/sewing/jersey',
'nahtzugabe': 'docs/sewing/seam-allowance',
'randnaht': 'docs/sewing/edgestitching',
'rayon': 'docs/sewing/rayon',
'serger': 'docs/sewing/serger',
'stecken': 'docs/sewing/pinning',
'steppstich': 'docs/sewing/slipstitch',
'strickbindung': 'docs/sewing/knit-binding',
'strickstoff': 'docs/sewing/knit-fabric',
'säumen': 'docs/sewing/hemming',
'topstitching': 'docs/sewing/topstitching',
'zickzackstich': 'docs/sewing/zig-zag-stitch',
'zugabe': 'docs/sewing/ease',
'zurückschneiden': 'docs/sewing/trimming',
'zuschnitt': 'docs/sewing/cutting',
'zwillingsnadel': 'docs/sewing/twin-needle',
},
es: {
'aguja gemela': "docs/sewing/twin-needle",
'basting': "docs/sewing/basting",
'bolsillos de doble soldadura': "docs/sewing/double-welt-pockets",
'buenas partes juntas': "docs/sewing/good-sides-together",
'cobertura': "docs/sewing/coverlock",
'corte': "docs/sewing/cutting",
'costura de bordes': "docs/sewing/edgestitching",
'dardos': "docs/sewing/darts",
'en el pliegue': "docs/sewing/on-the-fold",
'fijar': "docs/sewing/pinning",
'grano de tela': "docs/sewing/fabric-grain",
'hemming': "docs/sewing/hemming",
'hombro de punto alto': "docs/sewing/hps",
'hps': "docs/sewing/hps",
'jersey': "docs/sewing/jersey",
'margen de costura': "docs/sewing/seam-allowance",
'punto elástico': "docs/sewing/slipstitch",
'rayon': "docs/sewing/rayon",
'sargento': "docs/sewing/serger",
'suministros básicos de costura': "docs/sewing/basic-sewing-supplies",
'tela de tejidos': "docs/sewing/knit-fabric",
'topstitching': "docs/sewing/topstitching",
'trampa': "docs/sewing/trimming",
'vinculación de nudo': "docs/sewing/knit-binding",
'zig-zag stitch': "docs/sewing/zig-zag-stitch",
'único': "docs/sewing/ease",
},
fr: {
'aiguilles doubles': "docs/sewing/twin-needle",
'aisance': "docs/sewing/ease",
'au pli': "docs/sewing/on-the-fold",
'biais de jersey': "docs/sewing/knit-binding",
'bâtir': "docs/sewing/basting",
'coupe': "docs/sewing/cutting",
'droit fil': "docs/sewing/fabric-grain",
'dégarnir': "docs/sewing/trimming",
'endroit contre endroit': "docs/sewing/good-sides-together",
'fourniture de base pour la couture': "docs/sewing/basic-sewing-supplies",
'jersey': "docs/sewing/jersey",
'marge de couture': "docs/sewing/seam-allowance",
'ourlet': "docs/sewing/hemming",
'pinces': "docs/sewing/darts",
'poche passepoilée': "docs/sewing/double-welt-pockets",
'point glissé': "docs/sewing/slipstitch",
'point zig-zag': "docs/sewing/zig-zag-stitch",
'rayonne': "docs/sewing/rayon",
'viscose': "docs/sewing/rayon",
'recouvreuse': "docs/sewing/coverlock",
'sommet de l’épaule': "docs/sewing/hps",
'phe': "docs/sewing/hps",
'surjeteuse': "docs/sewing/serger",
'surpiqûre': "docs/sewing/topstitching",
'surpiqûre nervure': "docs/sewing/edgestitching",
'tissu maille': "docs/sewing/knit-fabric",
'épingler': "docs/sewing/pinning",
},
nl: {
'aan de stofvouw': "docs/sewing/on-the-fold",
'basis naaimateriaal': "docs/sewing/basic-sewing-supplies",
'bijknippen': "docs/sewing/trimming",
'coverlock': "docs/sewing/coverlock",
'draadrichting': "docs/sewing/fabric-grain",
'driegen': "docs/sewing/basting",
'dubbele paspelzak': "docs/sewing/double-welt-pockets",
'gebreide stof': "docs/sewing/knit-fabric",
'goede kanten op elkaar': "docs/sewing/good-sides-together",
'hoog punt schouder': "docs/sewing/hps",
'hps': "docs/sewing/hps",
'jersey': "docs/sewing/jersey",
'jersey biezen': "docs/sewing/knit-binding",
'knippen': "docs/sewing/cutting",
'naadtoeslag': "docs/sewing/seam-allowance",
'nepen': "docs/sewing/darts",
'overwijdte': "docs/sewing/ease",
'rayon': "docs/sewing/rayon",
'serger/overlock': "docs/sewing/serger",
'sierstiksel': "docs/sewing/topstitching",
'spelden': "docs/sewing/pinning",
'stiksels': "docs/sewing/edgestitching",
'stiksteek': "docs/sewing/slipstitch",
'tweelingnaald': "docs/sewing/twin-needle",
'zigzagsteek': "docs/sewing/zig-zag-stitch",
'zomen': "docs/sewing/hemming",
},
uk: {
'базові матеріали для шиття': "docs/sewing/basic-sewing-supplies",
'виточки': "docs/sewing/darts",
'джерсі': "docs/sewing/jersey",
'закріплення': "docs/sewing/pinning",
'зметування': "docs/sewing/basting",
'кишеня з подвійною листочкою': "docs/sewing/double-welt-pockets",
'коверлок': "docs/sewing/coverlock",
'крайовий шов': "docs/sewing/edgestitching",
'крій': "docs/sewing/cutting",
'лицьові сторони одна до одної': "docs/sewing/good-sides-together",
'на згині': "docs/sewing/on-the-fold",
'найвища точка плеча': "docs/sewing/hps",
'обрізка': "docs/sewing/trimming",
'поверхневий шов': "docs/sewing/topstitching",
'подвійна голка': "docs/sewing/twin-needle",
'припуск на шов': "docs/sewing/seam-allowance",
'підшивання краю': "docs/sewing/hemming",
'район': "docs/sewing/rayon",
'свобода облягання': "docs/sewing/ease",
'сергер': "docs/sewing/serger",
'строчка зигзаг': "docs/sewing/zig-zag-stitch",
'ткацьке переплетення': "docs/sewing/fabric-grain",
'трикотажна бийка': "docs/sewing/knit-binding",
'трикотажна тканина': "docs/sewing/knit-fabric",
'шовний стібок': "docs/sewing/slipstitch",
},
}
/*
* DO NOT CHANGE ANYTHING BELOW THIS LINE
*/
export const Term = ({ children }) => <SharedTerm {...{ jargon, children }} site="org" />

3
sites/org/next.config.mjs
View file

@ -2,9 +2,8 @@ import configBuilder from '../shared/config/next.mjs'
import i18nConfig from './next-i18next.config.js'
import { banner } from '../../scripts/banner.mjs'
import withBundleAnalyzer from '@next/bundle-analyzer'
import { jargon } from '../shared/jargon/index.mjs'
let config = configBuilder({ site: 'org', jargon })
let config = configBuilder({ site: 'org' })
config.i18n = i18nConfig.i18n
config.rewrites = async () => {
return [

48
sites/shared/components/jargon.mjs Normal file
View file

@ -0,0 +1,48 @@
import { useContext } from 'react'
import { useRouter } from 'next/router'
import { ModalContext } from 'shared/context/modal-context.mjs'
import { ModalWrapper } from 'shared/components/wrappers/modal.mjs'
import { DynamicMdx } from 'shared/components/mdx/dynamic.mjs'
/*
* Lowercase and strip dots, then check if we have a definition for the term
* If not, return false
*/
const asTerm = (term, jargon, lang) => {
if (typeof term !== 'string') return false
term = term.toLowerCase().split('.').join('')
return jargon[lang]?.[term] ? term : false
}
/*
* This is used for <em> tags.
* If it's a term, if it wraps a term in our terminology, it will make it clickable.
* If not, it will merely return the em tag.
*
* Since terms are different between sites, this takes a jargon object as prop
*/
export const Term = ({ children, site, jargon = {} }) => {
const { setModal } = useContext(ModalContext)
const router = useRouter()
const lang = router.locale
const term = asTerm(children, jargon, lang)
return term ? (
<button
className="italic underline decoration-warning decoration-dotted decoration-2 bg-warning bg-opacity-10 px-1 hover:bg-transparent hover:decoration-solid hover:cursor-help"
onClick={() =>
setModal(
<ModalWrapper>
<DynamicMdx site={site} language={lang} slug={jargon[lang][term]} />
</ModalWrapper>
)
}
>
{children}
</button>
) : (
<em>{children}</em>
)
}

3
sites/shared/components/mdx/index.mjs
View file

@ -16,6 +16,8 @@ import { collection } from 'site/hooks/use-design.mjs'
import { DesignMeasurements } from './design-measurements.mjs'
import { DesignOptions } from './design-options.mjs'
import { MeasieImage } from 'shared/components/measurements/image.mjs'
// Dev/Org jargon
import { Term } from 'site/components/jargon.mjs'
export const components = (site = 'org', slug = []) => {
const base = {
@ -30,6 +32,7 @@ export const components = (site = 'org', slug = []) => {
Tip: (props) => <Popout {...props} tip />,
Tldr: (props) => <Popout {...props} tldr />,
Warning: (props) => <Popout {...props} warning />,
em: (props) => <Term {...props} />,
}
const extra = {
pre: (props) => <Highlight {...props} />,

12
sites/shared/mdx/compile.mjs
View file

@ -16,11 +16,7 @@ import { remarkGithubImages } from './remark-github-images.mjs'
import rehypeHighlight from 'rehype-highlight'
import rehypeAutolinkHeadings from 'rehype-autolink-headings'
import rehypeSlug from 'rehype-slug'
import rehypeJargon from 'pkgs/rehype-jargon/src/index.mjs'
import rehypeHighlightLines from 'pkgs/rehype-highlight-lines/src/index.mjs'
// FreeSewing jargon and jargon transform
import { jargon as baseJargon } from 'shared/jargon/index.mjs'
import { jargonTransform } from './rehype-jargon-transform.mjs'
/*
* Compiles markdown/mdx to a function body
@ -29,7 +25,6 @@ export const compileMdx = async ({
md, // A string holding the markdown
site, // The site folder, one of 'org' or 'dev'
slug, // The slug to the page below the folder (like 'guides/plugins')
jargon = {}, // An object of jargon definitions. See rehype-jargon
fromGithub = false, // Set this to true when dynamically loading mdx from Github
}) => {
const mdx = String(
@ -56,13 +51,6 @@ export const compileMdx = async ({
remarkIntroAsFrontmatter,
],
rehypePlugins: [
[
rehypeJargon,
{
jargon: { ...baseJargon, ...jargon },
transform: jargonTransform,
},
],
[
rehypeHighlight,
{