How-to Guides

[bencroker]

Dear community, we need HELP transforming the Examples section of the Datastar website into How-to guides.

While the existing examples cover a lot of use-cases, they are unstructured, incomplete, poorly explained, and they would provide much more value as goal-oriented “recipes” that guide the reader towards a result.

Examples converted to How-to guides might read something like:

Click to Edit → Inline editing on click
Bulk Update → Bulk updating an item list
Click to Load → Load more results on click
Delete Row → Deleting a row in a table
...
Polling → Polling the backend at regular intervals
Bind Keys → Binding keydown events to specific keys
Classes → Toggling classes based on expressions
CSRF → Sending a CSRF token via a request header

Inspiration for this is taken from Diátaxis, specifically the section on How-to guides (please read before deciding to contribute).

If you would like to contribute, first check out the file changes in PR #517. You can propose a how-to guide that you’d like to write in a comment in this issue (not in the PR). Please propose one how-to guide at a time, and only propose a guide that you are willing to contribute a complete PR for.

To discuss ideas for how-to guides, please use the #documentation channel in the Datastar Discord server.

You should ideally be familiar with Datastar v1.0.0-beta.x and have already used it to build something. You should be comfortable writing markdown and willing to write some Go code for examples that require requests to the backend.

Proposals must follow this format:

---

TITLE: The title of the how-to guide you are proposing
SUMMARY: A brief summary of what it will cover
CODE SAMPLE: A code sample that it might use

---

If the proposal adheres to these key principles and generally aligns with the goal of this initiative, a file will be added to the PR and assigned to you. You can then fork the PR and work on your how-to guide in your own forked branch. When you feel it is ready for review, submit a pull request to PR #517.

Here is an example of a how-to guide that is a work in progress, for reference.

Please note that in the spirit of FOSS (free and open-source software), we reserve the freedom to decline suggestions and pull requests.

[td0m]

I'm happy to contribute one for redirects :)

[bencroker]

I'm happy to contribute one for redirects :)

Sounds great, @td0m! I created How to redirect the page from the backend for you at https://github.com/starfederation/datastar/pull/517/files

[SpiralOSS]

In for Hello World.

TITLE: Setting up the Hello World example
SUMMARY: A simple example that demonstrates streaming ServerSideEvents and reading signals.

[bencroker]

Excellent, @SpiralOSS! I created How to stream SSE events with a user-defined delay for you at https://github.com/starfederation/datastar/pull/517/files