add example wiring diagram

[mrbojangles3]

also experiment with adding line numbers for listings

[github-actions]

🚀 Deployed on https://preview-77--hedgehog-docs.netlify.app

[qmonnet]

Please find some small suggestions below.

Why is your commit title “initial commit”?

[qmonnet]

Suggested change

	serial: ABC123XYZ # (1)
	serial: ABC123XYZ # or we can also use "mac: 34:AD:61:00:02:03"

And get rid of the (somewhat) confusing footnote?

[mrbojangles3]

I am glad you brought this up. The footnote is something that I though would help, it is good to know that it doesn't. There are other docs that use the footnote style for YAML explanation. Which is what inspired this change.

[qmonnet]

I mean, the indication itself is useful. Having the footnote right below the YAML sample is OK, but looking at the example you link, I note that:

• the footnote reference and indicator are the same, both blue circles
• the marker is clickable, making it easier to find what part of the doc refers to it
• the note is too big to hold conveniently in a comment on the same line in the YAML sample, which is not really the case here so I'd just as well add the note in the comment, but that's me 🤷

In your case, I would at least make sure to use the same syntax at both locations if you want to keep the footnote, either (1) or 1., but not a mix.

[qmonnet]

By “confusing” I mostly meant that it was not super easy to find the footnote that it refers to; much of the confusion goes away if you use the same (1) syntax at both locations for example. I did not mean that the content of the note itself was confusing.

[mrbojangles3]

The commit message is because I was rushing, I will change it.

[pau-hedgehog]

1. Can also use mac: 34:AD:61:00:02:03 is confusing.

You could take the opportunity to refer to the line number instead, now that you are introducing them

I pushed a commit fixing a small typo.

Probably on another PR:

• We should refer to the hhfab validate to ensure the wiring YAML is correct
• Not to mention the visual validation you can do with a diagram! ;)
  (mermaid is supported and can be added in the doc)
• Maybe I'd take the opportunity to clarify how to define custom passwords. fab.yaml instructs you to:
  password hash use openssl passwd -5`

[mrbojangles3]

If we are okay with referring to line numbers I am good with switching to them. There is also the option to have the line numbers start at a given number. So we could have a big listing then break it up in sections to talk about it. Thoughts @pau-hedgehog and @qmonnet

[qmonnet]

If we are okay with referring to line numbers I am good with switching to them

I don't know. Is there a way to reference a specific line an turns that ref into a number under the YAML sample, or do you manually reference the line number, and risks the line number getting outdated if someone inserts more lines into the YAML snippet in the future?

[mrbojangles3]

It would be a pretty manual process. We would take the example file and have to manual start the line numbers ourselves. Very easy to get out of sync.

[qmonnet]

I'm still in favour of the footnote (or inline comment) in that case 😅.

[mrbojangles3]

What do you think of the look on the material for mkdocs webpage - https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#adding-annotations. It doesn't seem like we are getting the same functionality that is shown on the page.

[qmonnet]

Ooooh so that's what you were trying to do! That's cool, now we just need to understand how to make it work 🙂

[qmonnet]

Try adding a blank line between the YAML snippet and the annotation, just in case?

[pau-hedgehog]

What do you think of the look on the material for mkdocs webpage - https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#adding-annotations. It doesn't seem like we are getting the same functionality that is shown on the page.

We may be missing this: https://github.com/pawamoy/mkdocs-pygments ?

[mrbojangles3]

It was the blank line. Had to step away will update when back. Logan Blyth

…

On Fri, Mar 21, 2025 at 11:31 AM Pau Capdevila ***@***.***> wrote: What do you think of the look on the material for mkdocs webpage - https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#adding-annotations. It doesn't seem like we are getting the same functionality that is shown on the page. image.png (view on web) <https://github.com/user-attachments/assets/d5dc71e4-57a7-4af1-b814-caadd38ff0cf> We may be missing this: https://github.com/pawamoy/mkdocs-pygments ? — Reply to this email directly, view it on GitHub <#77 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABXI6A54RWTWYNYFQJG5JL2VQWGDAVCNFSM6AAAAABZL3QKUOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDONBTG4ZTCMRSGU> . You are receiving this because you authored the thread.Message ID: ***@***.***> [image: pau-hedgehog]*pau-hedgehog* left a comment (githedgehog/docs#77) <#77 (comment)> What do you think of the look on the material for mkdocs webpage - https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#adding-annotations. It doesn't seem like we are getting the same functionality that is shown on the page. image.png (view on web) <https://github.com/user-attachments/assets/d5dc71e4-57a7-4af1-b814-caadd38ff0cf> We may be missing this: https://github.com/pawamoy/mkdocs-pygments ? — Reply to this email directly, view it on GitHub <#77 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABXI6A54RWTWYNYFQJG5JL2VQWGDAVCNFSM6AAAAABZL3QKUOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDONBTG4ZTCMRSGU> . You are receiving this because you authored the thread.Message ID: ***@***.***>