search

postalserver / docs

📚 Documentation for the Postal mail server!
https://docs.postalserver.io
135 stars 59 forks source link

Update to Nuxt 3 #58

Closed casualmatt closed 4 months ago

casualmatt commented 5 months ago

Hi, Seen that postal 3. x is on its way and that Nuxt 2 is EOL, I'm offering to update the postal docs to Nuxt 3, based on Docus or even {Docs by Nuxt UI Pro](https://nuxt-ui-pro-template-docs.vercel.app/).

I own a copy of Nuxt UI Pro, which works very well with Nuxt Studio; I can ask for OSS access for it, which would help keep the docs up to date.

Let me know if I can contribute to that work.

jaydrogers commented 5 months ago

Sweet! I am stoked for v3.

I was the one who helped put together Nuxt Content back in the day.

My suggestions

Examples of Nuxt Content

We built all of these sites using Nuxt content and adapting the Tailwind Documentation Templates (Syntax and Protocol)

Each website is located within the SAME repository as the source code in the /docs folder. This helped us keep features in sync with the documentation (something that @adamcooke and @willpower232 should decide on).

Biggest thing needed from the core maintainers

  1. Is this a project that you want to tackle with v3?
  2. Do you want the docs to exists within the same repo of the main application?
  3. Do you have a design direction or preference?

Moving forward on this item

If this has the stakeholders support behind it and we all want to move forward with Nuxt Content, I can help with the deployment side of things to make sure it works well.

Let me know if I can be anything of value.

casualmatt commented 5 months ago
  • I would straight up use Nuxt Content (without Studio) so the community doesn't need to rely on any premium software

You could use Nuxt studio and edit the repo directly; one doesn't exclude the other. But if you have to write a lot of pages, Nuxt Studio makes it easier and quicker.

  1. Is this a project that you want to tackle with v3?

Nuxt 2 is EOL, so in some way, it has to be done; I volunteered to update it to Nuxt 3 + docus or "Docs by Nuxt UI Pro" (that for OSS is free normally).

  • Do you want the docs to exists within the same repo of the main application?

I am on the same page as you. It's probably a good idea to have a mono repo, but it's easy both ways.

3. Do you have a design direction or preference?

Let's keep it simple, a basic template like now; at least that's my idea.

willpower232 commented 5 months ago

Keeping the docs in their own repo is probably preferred as it ensures the docs can evolve separately without troubling the real maintainers.

Other than that, as long as the docs remain easy to manage markdown, I'm not super concerned how they become real HTML.

jaydrogers commented 5 months ago

Cool.

Maybe @adamcooke can chime in on design thoughts on what he'd like to see?

Then @casualmatt can submit a PR converting our old docs over?

Then I can help @casualmatt prep the site for deployment and work with @adamcooke to get it launched?

casualmatt commented 5 months ago

I think it will be static on GitHub like now. So there is no need for deployment.

I will wait for official confirmation that I can proceed but help is always appreciated.

jaydrogers commented 5 months ago

I'd like to fix the automated previews while we go through this process too. It's very helpful when reviewing PRs.

I've converted to using CloudFlare pages for this, but we can discuss that element later.

adamcooke commented 5 months ago

I really like the sites you posted earlier @jaydrogers - would be great to have something like this for Postal.

I don't know much about Nuxt Content nor what Nuxt Studio is or does! I'm happy to keep things as simple as possible.

Happy for you to do whatever is needed @casualmatt. If you have any specific questions which you need from me, do just ask.

adamcooke commented 5 months ago

I did forget to mention that I do prefer the idea of keeping the docs separate from the main repo (for now at least).

jaydrogers commented 5 months ago

Sweet! Simplicity definitely is key.

@casualmatt Do you want to throw together a PR and go from there?

If we're going to follow an example of the Server Side Up open source projects, it contains two major elements:

  1. Landing Page
  2. Docs

Question for @adamcooke & @willpower232

Do you want postalserver.io to redirect to GItHub as it does now? We have two options:

  1. Keep docs only at docs.postalserver.io (the way it is now)
  2. Have a landing page to be at postalserver.io and docs to be at postalserver.io/docs
willpower232 commented 5 months ago

the links are probably fine the way they are, there was probably a good reason to have postalserver.io pointing at the repo but its all up to @adamcooke

adamcooke commented 5 months ago

It would be nice for postalserver.io to actually have a site/docs on it rather than just going to the repo. I quite like the idea of landing page + docs all on postalserver.io.

I don't think there ever was a good reason to have it going the repo to be honest 😞

jaydrogers commented 5 months ago

Thanks for the feedback guys!

@casualmatt: Let us know what your comfort level is. Are you interested in putting something together for review?

I'd say it would require:

  1. Creating a design for landing page
  2. Converting our current docs to the new Nuxt Content structure

Design inspiration

Seems like @adamcooke is satisfied with a "dark mode" site following something along the feel and structure of:

Moving forward

Let us know what you're comfortable with and if you need any design assets, etc.

casualmatt commented 5 months ago

Yes, I will put down a PR this weekend, and we still start from there.

Perfect if u want to do the CICD for the preview, I don't like GitHub actions 🤣😂.

Ty for all the feedback @adamcooke.

adamcooke commented 5 months ago

Thanks @casualmatt - looking forward to it. Feel free to grab me on Discord (My username is .adamcooke) if you need anything quickly.

jaydrogers commented 5 months ago

Update

@casualmatt and I jumped on Discord and chatted for a bit. Here's what to expect.

Design update

Matt has an open source license that he can use for this: https://nuxt-ui-pro-template-docs.vercel.app/

It will basically look along the lines of this dark mode theme

image

Preview URLs

I will work to help get the preview URLs to work again.

Deployment

Once we get approval from @adamcooke and @willpower232, we can then work with @adamcooke to get the DNS configured correctly and possibly redirect docs.postalserver.io to postalserver.io/docs

jaydrogers commented 4 months ago

Just adding a note the related PR for this work is here: https://github.com/postalserver/docs/pull/59