Create a beautiful website with framework documentation

[nick-maslov]

• I have looked for existing issues (including closed) about this

Feature Request

Motivation

There are websites for Actix and Rocket, but not for Axum. I tried to convince my friend to switch to Axum and the first thing he said that it doesn't even have a website) I guess it's time to change it and make Axum more attractive.

Proposal

Let's build a beautiful website for Axum like Rocket has and fill it with the appealing and consistent documentation.

[davidpdrsn]

Yes. 100% yes! I have intentionally focused on docs.rs/axum because it provides good value for fairly low effort but axum absolutely should have a website and a logo.

I think it makes sense to develop something for tokio.rs. The repo for that is here. I could also be convinced the website needs to live in the axum itself but might be nicer to separate it out.

[nick-maslov]

Yes. 100% yes! I have intentionally focused on docs.rs/axum because it provides good value for fairly low effort but axum absolutely should have a website and a logo.

I think it makes sense to develop something for tokio.rs. The repo for that is here. I could also be convinced the website needs to live in the axum itself but might be nicer to separate it out.

Maybe it makes sense to have the Axum website on a subdomain of tokio.rs: something like axum.tokio.rs.

[davidpdrsn]

Could be yeah.

[westernwontons]

I would be interested in landing a hand to develop a website for axum, if there's an opening.

[davidpdrsn]

Maybe the easiest way to get started is to fork the tokio.rs repo and collaborate on that for a bit to see what you can come up with? Then there would also be a shared codebase to hack on. Once you then have something worthwhile you can open a discussion about merging the fork into the main https://github.com/tokio-rs/website repo.

In typical open source fashion all we need is someone to take lead and get the ball rolling. This won't be me but I encourage anyone interested to give it a shot! I'm willing up help out with reviews or questions you might have.

[nick-maslov]

Maybe the easiest way to get started is to fork the tokio.rs repo and collaborate on that for a bit to see what you can come up with? Then there would also be a shared codebase to hack on. Once you then have something worthwhile you can open a discussion about merging the fork into the main https://github.com/tokio-rs/website repo.

In typical open source fashion all we need is someone to take lead and get the ball rolling. This won't be me but I encourage anyone interested to give it a shot! I'm willing up help out with reviews or questions you might have.

I'd like to try to take the lead of this one. I'll get free time in about month and want to lend a hand to the website design and the further development.

P.s. It's my first time working on an open-source project, so I may need some help dealing with the organisation.

[nick-maslov]

I’d like the most knowledgeable guys to share their views of the overall website structure and particularly the content that should be present on the main page. If you look at the Rocket or the Actix websites, you can see the main page highlights the strengths of a framework, why you should use it compared to other frameworks, what key features it has, etc. I need some people to point out the key features and selling points of the Axum and maybe even formulate statements as they would want to see them on the main page. The more views and content I get, the easier it will be for me to craft the decent website.

[nick-maslov]

Also, I’d like to open a discussion on the ideas about Axum’s logo. What associations do people have, what elements can be used to create the relevant composition, why did you call it Axum at all, etc?

[nick-maslov]

Currently, I consider to setup the Docusaurus project with a unique main page and customized documentation pages.

[Altair-Bueno]

and customized documentation pages.

Is that something we want? Axum docs are already awesome, on par with other projects of the Tokio ecosystem. I would consider maintaining a whole separate source of truth is unnecessary.

As an alternative, I would consider a blog much more useful. It can be used to publish release notes, future work on the framework, users' success stories, team insights... Examples: Springs' blog and kani's

Note: Tokio already maintains a blog, but its focused on big releases only (axum 0.6.0, tokio 1,...) https://tokio.rs/blog/2023-01-03-announcing-turmoil.

[westernwontons]

For something like a blog I think Astro would be a fine choice.

[davidpdrsn]

I think building something for the existing tokio.rs site is a good way to start. All the setup (including deployment) is already done. We can always get axum.rs and have that redirect to tokio.rs/axum.

[nick-maslov]

If we already have satisfactory docs and the blog, maybe it makes sense to start just with Axum's promo landing page to make it more visually appealing, branded, and recognizable. And there we can place links to associated resources such as docs.rs.

[nick-maslov]

As an alternative, I would consider a blog much more useful. It can be used to publish release notes, future work on the framework, users' success stories, team insights... Examples: Springs' blog and kani's

After we get the promo page, we can consider creating Axum's own blog.

[davidpdrsn]

Why would axum need a blog?

What we need is documentation is isn't purely API level reference docs. See https://diataxis.fr.

[nick-maslov]

For the promo page, we now need to concentrate on 2 things: its content and Axum's logo ideas.

I need some knowledgeable people to share their ideas on sections it makes sense to add to the promo page, key features, and selling points of the Axum. The more views and content we get, the easier it will be to craft a decent main page.

Also, I’d like to open a discussion on the ideas about Axum’s logo. What associations do people have, what elements can be used to create the relevant composition, why did you call it Axum at all, etc?

[davidpdrsn]

@nikmas-dev also, please don't post several comments right after each other. It results in lots of notifications for people watching this repo.

[nick-maslov]

@nikmas-dev also, please don't post several comments right after each other. It results in lots of notifications for people watching this repo.

got it, ok))

[nick-maslov]

What we need is documentation is isn't purely API level reference docs. See https://diataxis.fr.

Yeah, I also feel docs.rs is more like an API reference than the complete docs. So I guess yes, it makes sense to work on the documentation due to https://diataxis.fr/

But the complete documentation is a big task that needs a lot of effort in writing tutorials, guides, and explanations. So, for now, I'd start from branding the Axum framework by creating the landing page for it.

[woile]

what about a simple landing page under axum.tokio.rs with 2 links: one to the api docs, and one to the mdbook with guides and tutorials? or even 4 links like the diataxis, but using only these 2 resources: either the mdbook or the api docs (axum.rs is taken sadly)

[wedwardbeck]

For the discussion on the logo (if considered) perhaps referencing a prior post on Discord here and the associated samples here would help. I am more connecting the dots between these conversations hoping to help.

[rsdlt]

Hi everyone, happy to work on this one.

@nikmas-dev will you be forking from tokio-rs/webiste to start working on a prototype?

Please let me know if you need a hand. Cheers.

[Darksonn]

This was discussed on the Tokio discord today, so I thought I would leave my advice here as well:

• If you start any large projects, be extremely careful that everyone is properly communicating to ensure that the work is not wasted. I have had to close a PR from a new contributor who spent a long long time on it, and it sucks really bad for everyone.
• Try to structure your work so that even partial progress is useful. For example, if you're going to write a guide, then start by writing the content as individual stand-alone articles. You can chain them together in a guide once you have all of your content. For the end-user, it sucks when a guide has lots of TODOs or a table of contents that lists missing articles.
• Don't start by creating a new website. Write the content first, and consider making a new website once you have stuff to put on it. It's very common for people who want their own blog to spend a bunch of time setting up a static site generator or whatever, then never get around to writing the first blog post. Don't fall into that trap, even if setting up docusaurus is more fun than writing content. For now, I would just put new axum content next to this article. You can always move it later.

[mo8it]

I don't think that we should reinvent the wheel like the documentation of Rocket. mdBook is very familiar to the Rust community and should in my opinion be used for non-API documentation.

Askama is one example: https://djc.github.io/askama/askama.html

[ruizdiazever]

mdBook is interesting to not reinvent the wheel, even so I think that the content is the most important and its quality, after all we are talking about Axum, the expectation is always high!

I give the FastAPI documentation as an example, one of the best I've seen since they are always updated, have many use cases, implementation, etc

https://fastapi.tiangolo.com/

[9876691]

I created https://rust-on-nails.com/ a while ago which uses Axum for server side rendering of web pages.

It's MIT licensed so could be used as a basis for anything that Axum does.

[sondrelg]

mdBook is great, and if it's open to suggestions, I'd consider vitepress, which the cargo lambda docs use. The best docs I've looked at in a while.

[mo8it]

If not mdbook, then I would definitely suggest Zola as a static site generator. It is written in Rust and used by many Rust fellows.

[jplatte]

Can we please stop this pointless discussion about tech choices when not even the scope of a custom website has been agreed upon?

The only obvious thing to build right now before discussing contents / scope seems to be a section on axum for the tokio.rs website, where I think the hard part will be defining how it will fit in that 3D layering graphic.

[nick-maslov]

Due to the lack of time currently I'll not be able to take lead of this one. But I encourage everybody to not forget about this issue as it may bring us much beauty, visual satisfaction, and many great resources to learn Axum!

[BillBarnhill]

I am looking to start contributing to Axum. I'd like to pick up the baton from @nikmas-dev and work as lead on this. I've worked with both Zola and mdbook before. I haven't used vitepress, but will check it out. I figure I can come up with a limited proof of concept in the next few weeks and post a link here for folks to review and comment on.

[davidpdrsn]

What @jplatte said is true. Before we make any tech choices we need have content. That is by far the hardest problem to solve so we need to start there.

It also makes sense to make things part of the existing tokio.rs website.