Skip to content

Commit 31334e9

Browse files
authored
Merge branch 'main' into cli_bc
2 parents 4951885 + 0f45bf3 commit 31334e9

331 files changed

Lines changed: 10180 additions & 1763 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
---
2+
name: contribute-blog
3+
description: >-
4+
Create, import, edit, or review posts for the
5+
official Flutter blog at flutter.dev/blog,
6+
including metadata, media, authors, and publication checks.
7+
---
8+
9+
# Contribute to the Flutter blog
10+
11+
## Editorial approach
12+
13+
Preserve the author's voice, intent, and requested scope.
14+
First person, contractions, anecdotes, humor, enthusiasm,
15+
and future-facing announcements can all be appropriate.
16+
Don't rewrite them merely to match documentation conventions.
17+
18+
Apply `write-technical-docs` and `format-markdown` selectively for clarity,
19+
accuracy, accessibility, links, code formatting, and sound structure.
20+
Their documentation-specific preferences aren't blanket blog requirements:
21+
semantic line breaks and an 80-character limit aren't required,
22+
especially when importing or lightly editing an existing post.
23+
24+
Fix or flag substantive issues with source fidelity,
25+
technical accuracy, accessibility, metadata, or rendering.
26+
Treat preference-only rewrites as suggestions
27+
unless copyediting was requested.
28+
29+
## Read relevant reference material
30+
31+
- For a new post, import, metadata or media change,
32+
structural edit, or full review, read
33+
[Flutter blog post format](references/post-format.md).
34+
- For a Google Doc import, also read
35+
[Import from Google Docs](references/google-doc-import.md).
36+
- To add or update an author or resolve an unknown author ID, read
37+
[Manage blog authors](references/authors.md).
38+
39+
A small prose-only correction might need no reference.
40+
Consult `sites/www/content/blog/data.yaml`,
41+
`sites/www/content/blog/authors.yaml`, comparable recent posts,
42+
or implementation source when a convention is unclear.
43+
44+
## Code and quality checks
45+
46+
- If changing or writing Dart or Flutter samples,
47+
apply `write-dart` and `write-flutter` as relevant.
48+
Validate complete examples when practical and
49+
label intentional omissions or pseudocode clearly.
50+
- Before calling a post ready,
51+
search the changed content for unresolved markers and placeholders,
52+
such as `TODO`, `TBD`, or placeholder notes.
53+
Report intentional markers or blockers instead of silently removing them.
54+
55+
## Validate proportionally
56+
57+
For a new post or a change to metadata or content,
58+
run the build and link-reference checks:
59+
60+
```bash
61+
dart run dash_site --site=www build
62+
dart run dash_site --site=www check-link-references
63+
```
64+
65+
When layout, media, metadata, or content significantly changes,
66+
consider previewing the site locally:
67+
68+
```bash
69+
dart run dash_site --site=www serve
70+
```
71+
72+
For a prose-only edit that doesn't change links,
73+
direct inspection of the content can be enough.
Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Manage blog authors
2+
3+
Use this reference when adding or updating an author,
4+
or when a post's author ID doesn't resolve.
5+
6+
Authors are defined in `sites/www/content/blog/authors.yaml`, and
7+
their local profile images live in `sites/www/content/blog/author_images/`.
8+
9+
The top-level key in `authors.yaml` is a stable content ID,
10+
not necessarily the author's current social handle.
11+
12+
## Add or resolve an author
13+
14+
Before adding a record,
15+
search `authors.yaml` by ID, display name, and profile URL.
16+
Use verified or author-provided details.
17+
Don't invent a name, profile, or image.
18+
For a new ID, choose a recognizable lowercase handle or concise stable slug,
19+
then insert the record alphabetically by ID.
20+
21+
`name` is required while `image`, `imageUrl`, and `link` are optional:
22+
23+
```yaml
24+
author-id:
25+
name: "Author Display Name"
26+
image: "author-id.webp"
27+
link: "https://github.com/author-id"
28+
```
29+
30+
- `image` names a local image file in `author_images/`.
31+
- `imageUrl` accepts an external URL to use as a fallback to `image`.
32+
Prefer a local `image` over setting `imageUrl`. Don't set both.
33+
- `link` is the destination linked from the byline. Prefer their GitHub profile.
34+
35+
## Author images
36+
37+
Name a local image after the exact author ID and
38+
use its real lowercase `.jpg` or `.webp` extension,
39+
such as `author-id.webp`.
40+
Optimize it for a small square display and a centered circular crop.
41+
Use an author-supplied or appropriately reusable image.
42+
43+
## Update an author
44+
45+
Keep the existing ID when an author's name, handle, link, or image changes.
46+
If the ID must change, update every occurrence in post frontmatter.
47+
48+
When replacing an image with a different filename or extension,
49+
search for references to the old file before removing it.
50+
Don't remove an apparently unused author without checking all posts.
51+
52+
## Configure the authors of a post
53+
54+
In a post's `index.md` frontmatter:
55+
56+
For a single author, use a YAML scalar:
57+
58+
```yaml
59+
author: author-id
60+
```
61+
62+
For multiple authors, use an ordered list:
63+
64+
```yaml
65+
author:
66+
- first-author
67+
- second-author
68+
```
69+
70+
List order controls the displayed byline.
Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# Import from Google Docs
2+
3+
Use this reference to convert an authored Google Doc into a Flutter blog post
4+
without turning the import into an unsolicited rewrite.
5+
6+
## Get the source
7+
8+
First, try to download the source yourself.
9+
Open the document in an authenticated browser and choose
10+
**File > Download > Web Page (.html, zipped)**.
11+
An authenticated Google Docs or Drive connector is also suitable
12+
if it can produce the complete HTML export and original media.
13+
14+
If you can't access the document, the download fails,
15+
or the export is incomplete,
16+
ask the user to download and provide the HTML zip.
17+
Don't reconstruct content that the available source omits.
18+
19+
Import the document body as exported.
20+
Ignore comment threads and suggestion metadata,
21+
don't reproduce or act on them.
22+
Extract exports into a temporary directory and
23+
don't commit the source archive or intermediate conversion files.
24+
25+
## Convert content, not export debris
26+
27+
Preserve the document's structure and meaning,
28+
including headings, prose, lists, tables, emphasis, links,
29+
code, images, and captions.
30+
Convert ordinary content to clean Markdown,
31+
using site components when they provide necessary behavior.
32+
33+
Strip Google Docs export artifacts:
34+
35+
- **Redirects**:
36+
Replace Google redirect and tracking URLs with their direct destinations.
37+
- **Styling spans & non-breaking spaces**:
38+
Remove non-relevant markup and structure, such as
39+
inline CSS, font declarations, classes, empty anchors, and wrapping spans.
40+
- Replace ` ` with standard whitespace.
41+
- **Code snippets**:
42+
Convert exported code to fenced Markdown blocks
43+
with appropriate language identifiers, such as `dart` or `bash`.
44+
Google Docs might represent code as `<p>` tags with
45+
`&nbsp;` indentation or as single-cell tables.
46+
- **Titles**:
47+
Don't replicate the document title as an `# H1` heading in the Markdown body.
48+
The `title` in the post's frontmatter supplies the page H1.
49+
- **Footnotes**:
50+
Preserve footnote content,
51+
but omit generated Google Docs anchor navigation links.
52+
- **Videos**: Convert standalone YouTube links into `<YouTubeEmbed>` components.
53+
54+
Keep the author's person, tone, pacing, spelling variety,
55+
heading style, and rhetorical choices unless editing was requested.
56+
Correct conversion errors,
57+
but surface optional prose changes separately.
58+
59+
## Resolve authors
60+
61+
Identify the ordered authors from an explicit byline or user context,
62+
not from document ownership or editor metadata.
63+
64+
To resolve their IDs and configure the post's frontmatter,
65+
follow the steps in [Manage blog authors](authors.md).
66+
If the source lacks enough information to identify or resolve an author,
67+
ask the user for their GitHub or other profile URL.
68+
69+
## Reconcile images
70+
71+
Map each exported image to
72+
its source position, caption, and purpose
73+
before renaming or moving it:
74+
75+
- Place images in the post's `images/` directory
76+
with concise, descriptive names.
77+
- Keep the highest-quality intended source.
78+
Convert static raster images to WebP when quality and clarity are preserved.
79+
- If the image is a JPEG, prefer a `.jpg` extension over `.jpeg`.
80+
- Preserve intentional animation
81+
and provide a static `socialImage` when needed.
82+
- Follow the alt text and `<DashImage>` guidance in
83+
[Flutter blog post format](post-format.md).
84+
- If an image's purpose or placement is ambiguous,
85+
ask for guidance rather than guessing.
86+
87+
## Check fidelity
88+
89+
Compare the converted post with the source section by section.
90+
Confirm that no prose, list item, code block, table row, image, caption,
91+
footnote, or intended link is missing or misplaced.
92+
Check heading hierarchy, link destinations, image-caption pairings,
93+
and meaningful emphasis.
94+
Report any placeholder or editorial hold in the document body
95+
that prevents the post from being ready.
96+
97+
Finish with the format and accessibility checks in
98+
[Flutter blog post format](post-format.md)
99+
and the validation workflow in the [parent skill](../SKILL.md).

0 commit comments

Comments
 (0)