|
| 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 | + ` ` 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