Temporary Developer Site Options

[ALRubinger]

(Please no replies before the workweek starts). 😉

I've now stood up two options for the Developer Site for Miami. Instructions for building each are in the CONTRIBUTING.md docs of the two repos.

Docusaurus

Source: https://github.com/TBD54566975/developer-site-docusaurus
Site: https://tbd54566975.github.io/developer-site-docusaurus/

This one is done in React and is both more powerful and more complex. We still have the option to add simple pages as Markdown. Skinning will be more difficult and take more time or expertise to wrangle React to slim it down and do what we want. It also comes with a Blog built in. If we are going to be authoring blog posts before, during, and immediately following Miami, I think the extra effort may be worth it. But we'd need to commit to blogging to justify the extra effort.

MkDocs

Source: https://github.com/TBD54566975/developer-site
Site: https://tbd54566975.github.io/developer-site/

I re-skinned this using the Material theme and I think that one is much more clean, modern, and closer to what we'd want to skin it to. It meets my bar for Miami, but it may be underpowered if we want more features going forward, or we want to see how far we can get on our own on a Developer Site before bringing in extra hands. And no blog in the short term.

My opinion: Docusaurus, if someone will help w/ React and skinning. I won't have the cycles.

DISCUSS?

In particular: @angiejones, @mkingtbd. :)

[mistermoe]

my name is not @angiejones or @mkingtbd so feel free to ignore this 🙃 :

Firstly, @ALRubinger , many props for getting docusaurus up and running. Really happy that you gave it a shot.

My opinion:
I think docusaurus makes the most sense.

As you mentioned, docusaurus does have the ability to include simple pages as markdown which you've already done. This takes us just as far as Mkdocs does with the added benefit of looking way better (IMO). Then, we have the potential for tons of customization. Might as well go with docusaurus. I mean, we get dark mode right out of the gate!

Agreed that skinning is a bit more complex with docusaurus. Thankfully that complexity can be championed by anyone who knows css + some react. Not even complicated react (e.g. managing state, talking to backend APIs etc.). We could start by asking anyone within Block that knows a bit of react that would be interested in contributing to our open-source efforts. I would offer to take it on but i'm already jam-packed with stuff to do. Happy to review. Styling and layout docs.

Finally, there's baked in support for SEO, easy-to-add search, and a plugin system.

Here's a list of showcased sites built on docusaurus that are open-source: https://docusaurus.io/showcase

[ALRubinger]

Great extra context, @mistermoe.

Right now I'm digging into Docusaurus to see if we can stand up the Developer site just just as a temporary holdover, but as a stable base upon which to build the Developer site going forward. It's an option we've got to review with @mkingtbd and I'm vetting it for technical stability to make a recommendation.

[ALRubinger]

If it's too heavy a lift, MkDocs is a fine solution for Miami. And the MarkDown content we make for it will easily port elsewhere.