Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: seed docs script #231

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open

chore: seed docs script #231

wants to merge 6 commits into from

Conversation

jbmoelker
Copy link
Member

@jbmoelker jbmoelker commented Dec 21, 2024

Note

The functionality itself is ready. The only issue is a failing Astro check in the CI lint-code job. See comment. I could use some help resolving that issue.

Changes

  • Adds seed script documentation, creating (or updating) CMS records for all docs/*.md files.
  • Adds a documentation page (if none exists; with slug documentation) and uses it as a parent page.
  • Adds a page partial (if none exists; titled "Documentation index") as a convenient list of links to all documentation pages.
  • Note: dependencies are kept outside root package.json to resolve conflicts. Also the seed dependencies are not needed for other projects using Head Start.

Associated issue

Related to #27, though that issue is mainly about seeding required content.

How to test

  1. Check out this feature branch
  2. Run npm run seed:docs (you may want to switch to a new sandbox environment for this)
  3. Verify the docs are added to the current DatoCMS environment (in ./datocms-environment.ts)
  4. Update a documentation file
  5. Re-run the script
  6. Verify the related record in the CMS is updated
  7. Review the documentation pages in the browser
  8. Verify links in the pages (relative and external) work correctly

Checklist

  • I have performed a self-review of my own code
  • I have made sure that my PR is easy to review (not too big, includes comments)
  • I have made updated relevant documentation files (in project README, docs/, etc)
  • I have added a decision log entry if the change affects the architecture or changes a significant technology
  • I have notified a reviewer

Dependencies outside root package.json to resolve conflicts. Also the seed dependencies are not needed for other projects using Head Start.

to do:
- better link replacement in md files
- add a partial listing all documents?
Copy link

cloudflare-workers-and-pages bot commented Dec 21, 2024

Deploying head-start with  Cloudflare Pages  Cloudflare Pages

Latest commit: a00c799
Status: ✅  Deploy successful!
Preview URL: https://4274c3b9.head-start.pages.dev
Branch Preview URL: https://chore-seed-docs.head-start.pages.dev

View logs

@jbmoelker jbmoelker added help wanted Extra attention is needed needs refinement and removed needs refinement labels Dec 21, 2024
@jbmoelker jbmoelker marked this pull request as ready for review January 2, 2025 16:08
import { fromMarkdown } from 'mdast-util-from-markdown';
import type { Root } from 'mdast';
import { toHast } from 'mdast-util-to-hast';
import { hastToStructuredText, type HastRootNode } from 'datocms-html-to-structured-text';
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Astro check in the CI lint job fails on this module. Not sure why it's not found. Locally I can verify it exists. Maybe it has to do with the "type": "commonjs" in package.json? But I can't change that to "module" as then running DatoCMS migrations will fail 🤷 .

It's a bit of a non-issue. Astro check shouldn't even lint this file and just stick to src/. But I'm unable to configure that. What I could do as a workaround is in the CI lint job, delete config/datocms/scripts/ before running npm run lint:astro. What do you think?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

patch available as PR: #241

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
help wanted Extra attention is needed
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant