Card-builder documentation

[aloosley]

Hi group,

Thanks for developing this tool!

To make this potential wide-audience tool more accessible to all, it would be great to see the card-builder documentation improved, specifically the local development section. From my perspective (I very rarely work with Javascript), I see the main challenges as follows:

• Running npm run build does not seem to work out of the box (I had to install esbuild and sass)
• There is no clear instructions for how to run the two lines of JavaScript given
• A developer wants to build a card from an md-file, but the instructions only show how to build a card from a single lined JavaScript string

[andrewzaldivar]

Hello,

Thank you for checking out our resources and your mindful feedback!

I see two issues raised that need addressing:

• To your first point, we could include a full list of dependencies in the README as a heads-up. I'll go through the installation process once more to confirm what's required before updating the README.
• To your second and third point, I think the best thing we could do to improve clarity is to create a sample JS file that opens a given file and reads it. That'll take us some time, but we'll prioritize it and have it ready in the coming week or so. In the interim, one quick option is to use the Card Builder on the website to create a Data Card. You would just have to copy your Markdown file into the builder. But that way you don't have to use JS.

Unless you have any specific follow-ups, I'll create a separate issue for that sample JS file and will close this issue once I update the README to include the full list of dependencies.

[aloosley]

Just a comment, I don't think updating the README.md with a full list of dependencies is a good idea because then you (and your maintainers) will have a duplication of truth (two lists of dependencies that you'll have to keep in sync, one in package.json and one in README.md).

Rather than that extra complexity, the dependencies should simply be maintained via the package.json, and the build script (ie. npm run build) should work out of the box as documented in the README.md. This keeps your documentation and installation simple.

Do you mind if I create a corresponding pull request?

As for the last part, creating a template md file and html that runs the script would be great. Please link the new issue here and I'll share a possible solution.

Thanks.

[andrewzaldivar]

That's an excellent point! Yes, feel free to create a corresponding pull request. I'll review it.

I also created #17. Feel free to share your possible solution there.

Again, you have my gratitude.