Skip to content

Commit 9b562c5

Browse files
ksen0ksen0
committed
Documented remix attribution schema
1 parent 7b6d957 commit 9b562c5

File tree

5 files changed

+128
-93
lines changed

5 files changed

+128
-93
lines changed

‎docs/content_overview.md

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,43 @@
1111
- Stored in `/src/content/examples/`
1212
- All translations are stored and edited directly in this repo under the corresponding language folder in `/src/content/examples/`
1313

14+
To add attribution, you can use the following block in the headers, listing in chronological order all arrtibutions. Below is the example from `examples/animation-and-variables-conditions/`:
15+
16+
```yaml
17+
remix:
18+
- description: Inspired by
19+
20+
attribution:
21+
- name: Prof. WM Harris
22+
URL: https://people.rit.edu/wmhics/
23+
24+
codeURL: https://github.com/processing/p5.js-website-legacy/blob/main/src/data/examples/en/04_Control/05_Logical_Operators_2.js
25+
codeLabel: pre-2023 code
26+
27+
- description: Revised by
28+
29+
attribution:
30+
- name: Caleb Foss
31+
URL: https://github.com/calebfoss
32+
33+
codeURL: https://github.com/processing/p5.js-example/tree/main/examples/02_Animation_And_Variables/03_Conditions
34+
codeLabel: 2023 revision code
35+
36+
- collectivelyAttributedSince: 2024
37+
```
38+
39+
This will result in a block that lists, in order, the initial inspiration; any revision or other remix; and the collective attribution statement that begins in 2024: "From 2024 onwards, edited and maintained by p5.js Contributors and the Processing Foundation. Licensed under CC BY-NC-SA 4.0."
40+
41+
A remix can be many things ([here is an example analysis of sketch remixing (PDF)](https://dl.acm.org/doi/pdf/10.1145/3563657.3595969)); the `description` will be by default "Remixed by", so a more specific description is recommended.
42+
43+
If the `collectivelyAttributedSince` information is missing, then no year will be included, but the collective attribution statement will still show: "Edited and maintained by p5.js Contributors and the Processing Foundation. Licensed under CC BY-NC-SA 4.0."
44+
45+
Each item in the remix history must have an original codeURL and/or at least one person listed in the attribution section. When multiple people are listed, their names will be shown in that order. For people, URLs are optional but recommended.
46+
47+
If no `codeLabel` is given but there is a `codeURL`, then the default label "code" will be used - however, for accessibility, it is strongly recommended to use short, descriptive labels.
48+
49+
---
50+
1451
## Tutorials
1552

1653
- Stored in `/src/content/tutorials/`

‎src/content/examples/config.ts

Lines changed: 12 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -9,31 +9,34 @@ export const examplesCollection = defineCollection({
99
type: "content",
1010
schema: ({ image }) =>
1111
z.object({
12-
1312
// Title of the example
1413
title: z.string(),
1514
oneLineDescription: z.string(),
16-
1715
// Aria label used for the live example code
1816
arialabel: z.string().optional(),
1917
featured: z.boolean().optional(),
2018
relatedReference: z.array(reference("reference")).optional(),
2119
featuredImage: image(),
2220
featuredImageAlt: z.string().optional().default(""),
2321

24-
// Start of collective attribution
25-
collectivelyAttributedSince: z.number().optional(),
26-
2722
// Optional list of remixes to add to license
2823
remix: z
2924
.array(
3025
z.union([
3126
z.string(),
3227
z.object({
33-
attributionURL: z.string().optional(),
34-
attributionLabel: z.string().optional(),
35-
remixURL: z.string().optional(),
36-
remixLabel: z.string().optional(),
28+
description: z.string().default("Remixed by"),
29+
codeURL: z.string().optional(),
30+
codeLabel: z.string().optional(),
31+
attribution: z
32+
.array(
33+
z.object({
34+
name: z.string(),
35+
URL: z.string().optional(),
36+
})
37+
)
38+
.optional(),
39+
collectivelyAttributedSince: z.number().optional(),
3740
}),
3841
])
3942
)
@@ -42,20 +45,3 @@ export const examplesCollection = defineCollection({
4245
}),
4346
});
4447

45-
/**
46-
* The `remix` field lets you add remix attributions in two ways:
47-
* 1. Full objects with all details.
48-
* 2. Short string keys that refer to predefined entries in `remixLookup`.
49-
* When rendering (in ExampleLayout.astro), these keys are replaced
50-
* with their full details from `remixLookup`.
51-
*/
52-
53-
type RemixEntry = {
54-
attributionURL: string;
55-
attributionLabel: string;
56-
remixURL: string;
57-
remixLabel: string;
58-
};
59-
60-
61-
// TODO instead of this emit a warning if there's multiple URLs used for the same person

‎src/content/examples/en/01_Shapes_And_Color/00_Shape_Primitives/description.mdx

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,10 +11,10 @@ remix:
1111
- description: Revised in 2023 by
1212
attribution:
1313
- name: Darren Kessner
14-
codeURL:
15-
codeLabel:
16-
- description: Based on
17-
code URL: codeLabel: archived version
14+
URL: https://github.com/dkessner
15+
- collective:
16+
since: 2024
17+
1818
---
1919

2020
This program demonstrates the use of the basic shape

‎src/content/examples/en/02_Animation_And_Variables/03_Conditions/description.mdx

Lines changed: 20 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,27 @@ featuredImageAlt: A small black circle on a rainbow, lattice-shaped path, on top
44
title: Conditions
55
oneLineDescription: Use if and else statements to make decisions while your sketch runs.
66

7-
collectivelyAttributedSince: 2024
87
remix:
9-
- attributionURL: https://people.rit.edu/wmhics/
10-
attributionLabel: Prof. WM Harris
11-
- revision-2023-calebfoss
8+
- description: Inspired by
9+
10+
attribution:
11+
- name: Prof. WM Harris
12+
URL: https://people.rit.edu/wmhics/
13+
14+
codeURL: https://github.com/processing/p5.js-website-legacy/blob/main/src/data/examples/en/04_Control/05_Logical_Operators_2.js
15+
codeLabel: pre-2023 code
16+
17+
- description: Revised by
18+
19+
attribution:
20+
- name: Caleb Foss
21+
URL: https://github.com/calebfoss
22+
23+
codeURL: https://github.com/processing/p5.js-example/tree/main/examples/02_Animation_And_Variables/03_Conditions
24+
codeLabel: 2023 revision code
25+
26+
- collectivelyAttributedSince: 2024
27+
1228
---
1329

1430
If and else statements allow a

‎src/layouts/ExampleLayout.astro

Lines changed: 55 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,6 @@
22
import type { CollectionEntry } from "astro:content";
33
import Head from "@components/Head/index.astro";
44
import { setJumpToState } from "../globals/state";
5-
import { remixLookup } from "../content/examples/config";
65
import { getCurrentLocale, getUiTranslator } from "../i18n/utils";
76
import {
87
generateJumpToState,
@@ -42,13 +41,17 @@ const relatedReferences =
4241
)
4342
: [];
4443
45-
// Rather than using example.data.remix, use resolvedRemix
46-
// Which fills in widely-used attributions to avoid duplication
47-
const resolvedRemix = example.data.remix.map((entry: any) =>
48-
typeof entry === "string" ? remixLookup[entry] : entry
49-
);
50-
5144
const { Content } = await example.render();
45+
46+
const collectivelyAttributedSince = example.data.remix?.reduce((acc, item) => {
47+
if (typeof item === "string") return acc;
48+
if (item.collectivelyAttributedSince) {
49+
return item.collectivelyAttributedSince;
50+
}
51+
return acc;
52+
}, null);
53+
54+
5255
---
5356

5457
<Head
@@ -73,67 +76,60 @@ const { Content } = await example.render();
7376
<div class="rendered-markdown">
7477
<p>
7578

76-
<a href={Astro.url.pathname}>{example.data.title}</a>:
79+
<a href={Astro.url.pathname}>{example.data.title}</a>:{" "}
7780

78-
{resolvedRemix?.map((item, i) => (
79-
<>
80-
{i > 0 && " "}
81-
{item.remixLabel ? (
82-
<>
83-
{item.remixURL ? (
84-
<>
85-
<a href={item.remixURL}>{item.remixLabel}</a> by
86-
</>
87-
) : (
88-
item.remixLabel
89-
)}
81+
{example.data.remix?.map((item, i) => {
82+
if (typeof item === "string") return null;
9083

91-
{item.attributionLabel && (
84+
const parts = [];
85+
86+
if (!item.collectivelyAttributedSince && (item.attribution || item.codeURL)) {
87+
parts.push(<>{item.description}</>);
88+
89+
if (item.attribution?.length) {
90+
parts.push(
91+
<>
92+
{" "}
93+
{item.attribution.map((a, j) => (
9294
<>
93-
{" "}
94-
{item.attributionURL ? (
95-
<a href={item.attributionURL}>{item.attributionLabel}</a>
96-
) : (
97-
item.attributionLabel
98-
)}.
95+
{a.URL ? <a href={a.URL}>{a.name}</a> : a.name}
96+
{j < item.attribution.length - 1 ? ", " : !item.codeURL ? "." : ""}
9997
</>
100-
)}
101-
</>
102-
) : item.attributionLabel ? (
103-
<>
104-
Remixed from{" "}
105-
{item.attributionURL ? (
106-
<a href={item.attributionURL}>{item.attributionLabel}</a>
107-
) : (
108-
item.attributionLabel
109-
)}.
98+
))}
11099
</>
111-
) : null}
112-
</>
113-
))}
114-
115-
{example.data.collectivelyAttributedSince ? (
116-
<>
117-
From {example.data.collectivelyAttributedSince} onwards, edited and maintained by
118-
</>
119-
) : (
120-
<>
121-
Edited and maintained by
122-
</>
123-
)}
124-
125-
<a href="https://github.com/processing/p5.js?tab=readme-ov-file#contributors">p5.js Contributors</a>
126-
and the
100+
);
101+
}
102+
103+
if (item.codeURL) {
104+
parts.push(
105+
<span>
106+
(<a href={item.codeURL}>{item.codeLabel || "code"}</a>).
107+
</span>
108+
);
109+
}
110+
}
111+
112+
return <span key={i}>{i > 0 && " "}{parts}</span>;
113+
})}
114+
115+
{collectivelyAttributedSince ? (
116+
<>From {collectivelyAttributedSince} onwards, edited and maintained by{" "}</>
117+
) : (
118+
<>Edited and maintained by{" "}</>
119+
)}
120+
<span>
121+
<a href="https://github.com/processing/p5.js?tab=readme-ov-file#contributors">p5.js Contributors</a>{" "}
122+
and the{" "}
127123
<a href="https://processingfoundation.org/people">Processing Foundation</a>.
128124
Licensed under{" "}
129125
<a href="https://creativecommons.org/licenses/by-nc-sa/4.0/">CC BY-NC-SA 4.0</a>.
126+
</span>
127+
</p>
128+
<img src="/images/by-nc-sa.svg" />
129+
</div>
130130

131-
</p>
132-
<img src="/images/by-nc-sa.svg" />
133-
</div>
134-
135-
<EditableSketch code={code} />
136-
<p>{example.data.arialabel}</p>
131+
<EditableSketch code={code} />
132+
<p>{example.data.arialabel}</p>
137133

138134
</div>
139135
<div class="grid gap-y-4xl lg:gap-y-mb-3xl mt-2xl">

0 commit comments

Comments
 (0)