Next-auth: Documentation Site

[ndom91]

Hey so I was thinking, one thing this project is missing is a documentation site.

I don't know of any nextjs based static documentation generator type projects like docusaurus from facebook or docz with gatsby, but I could whip up a demo docz site which just takes the markdown pages that are already here / in the process of being written for v2, and display them nicely / makes them searchable, etc.

We could throw it up on now.sh and we'd be good to go.

Also js.org allows open source projects to grab subdomains for free, so I could get us next-auth.js.org to redirect to our docs page or the repo or whatever you want.

What do you think @iaincollins ? Might be nice to release a good looking docs page in tandem with v2 soon :)

[iaincollins]

I think this is a great idea! I completely agree I think would be helpful to have a site with solid documentation and example usage (especially for advanced configuration options).

If you can set up next-auth.js.org that would be great!

[ndom91]

@iaincollins great! I've got a working example up here: https://next-auth-docs.now.sh/

I couldn't find a logo for the project anywhere, but if you have one you'd like me to use or prefer any specific primary / secondary colors for the project just let me know.

Currently this is all coming out of a subfolder (/docs) of a fork I made of next-auth/next-auth-2 about an hour ago ndom91/next-auth.

I can keep it separate, or if you'd like, I can make a PR to merge the docs subfolder back into here. Just let me know how you prefer to do it.

EDIT: Now that we have https://next-auth-docs.now.sh/ I'll make a PR to that js.org repo to get that subdomain next-auth.js.org

[iaincollins]

This looks fantastic, a PR would be great!

I really like how it extracts headings and the code block highlighting makes the docs easy to read.

I have no thoughts on branding / colours at the moment! (Agree I think it's helpful to have consistent branding, just don't have a view on it currently!)

cc @LoriKarikari who has been working on provider docs

[ndom91]

Okay yeah no problem. I'll put together a PR then shortly. I'm assuming you want it to your v2 branch, right? Not the master?

Also how should we manage the now.sh hosting / deploying? It currently runs under my now.sh account and is linked to my fork of the repo. If the docs move into your primary repo, we have to relink the now.sh project.

I'm not sure the best way to go about this to be honest, but I think I need to have some sort of rights to this repo in order to link it inside my now.sh dashboard.

The other option would be that I completely delete my now.sh project and you can create a new one there. Important is just that you use the same project name so that we get the same ...now.sh url so that next-auth.js.org points to the correct place.

Thoughts?

EDIT: Oh also, currently the docs are "duplicated" because the markdown files are still in the root of the project, i.e. README.md, README-CLIENT.md, etc. I'll tighten up the normal README.md a bit in my PR so that Github still has a nice readme on the frontpage, with links to the docs page of course. The other documentation markdown files (README-CLIENT, AUTH, etc.) can just be deleted out of the root so that they're only located in the /docs subfolder then, right?

CC: @LoriKarikari

[LoriKarikari]

Also, what's the name of this project? Is it NextAuth or next-auth? 😅 want to be consistent on the website and the documentation.

[iaincollins]

Oh also, currently the docs are "duplicated" because the markdown files are still in the root of the project, i.e. README.md, README-CLIENT.md, etc. I'll tighten up the normal README.md a bit in my PR so that Github still has a nice readme on the frontpage, with links to the docs page of course. The other documentation markdown files (README-CLIENT, AUTH, etc.) can just be deleted out of the root so that they're only located in the /docs subfolder then, right?

That sounds perfect!

I guess only doc we need in the root is the README.md, which also gets displayed on the NPM page and probably should make sense to have a quick summary, example usage, links to more docs and credits to contributors.

[iaincollins]

Also how should we manage the now.sh hosting / deploying? It currently runs under my now.sh account and is linked to my fork of the repo. If the docs move into your primary repo, we have to relink the now.sh project.

I'm not sure the best way to go about this to be honest, but I think I need to have some sort of rights to this repo in order to link it inside my now.sh dashboard.

Ooh, we could make a Team in now.sh maybe, so multiple folk can access? (I'm not sure if you can move existing URLs into a team, but I guess we could create a new one/redirect to another URL).

[ndom91]

Yeah great, I'll make a draft of that README in my PR then and you can obviously adjust it then however you see fit.

Regarding the hosting - I just thought of something else, maybe its easier to host it out of github pages? They have docs for that specific setup here: https://v2.docusaurus.io/docs/deployment/#deploying-to-github-pages

EDIT: Ah the docs are specific to travis CI though. I'm sure we could get it workign with a github action as well though. It just needs to run npm run build and then tell github pages to look in the /build folder.

[iaincollins]

Okay yeah no problem. I'll put together a PR then shortly. I'm assuming you want it to your v2 branch, right? Not the master?

If it's helpful and everyone is cool with that I am happy for us to merge the current v2 branch into master anytime now.

RE: Docs, oh that would be fine, I'm super happy with GitHub Actions and don't mind setting that up, as will probably want to do that to auto-publish releases from master to canary/beta on NPM at some point.

[ndom91]

I just checked, teams in vercel / now.sh are not free at all unfortunately :/ $20 per seat with 14 day trial

[ndom91]

Okay then what do you think about this?

I'll clean up the docs situation in the root folder and make a PR and see if I can find a github action template for deploying docusaurus. If that all looks good you could accept that and then merge the entire v2 branch into yuor master?

[ndom91]

Okay PR is up: https://github.com/iaincollins/next-auth/pull/119

@LoriKarikari if you want to add any docs, simply put them in the /docs/docs/ folder and don't forget to add the page to the sidebar at /docs/sidebar.js. (I know its a bid odd with the docs subfolder for the docs subproject, and then another docs subfolder for the markdown content itself :/ )

The sidebar works like this:

The id, i.e. getting-started is just the filenames in relation to the /docs/docs folder. So if you create a new doc here, for example: /docs/docs/providers.md then the sidebar.js entry would just be:

'v2': [
  ...
  'providers',
],

[iaincollins]

Also, what's the name of this project? Is it NextAuth or next-auth? 😅 want to be consistent on the website and the documentation.

@LoriKarikari Thank you for raising that! That is a great question.

The NPM package has always been next-auth but I've tired (but sometimes failed) to use NextAuth as the name when referencing it in documentation.

To add to confusion, I see some guys with a mobile auth package registered the domain nextauth.com and renamed their product, which was previously called n-auth, to NextAuth.

They also grabbed the org name github.com/next-auth. To be clear though, they did this after I'd published NextAuth (this package), they just renamed their product with the same name.

This is a bit annoying and I'm not sure what to do about it. I am happy to keep calling this package NextAuth as not only did this package come first, but it doesn't look like they have any published open source software anyone is using (just the old n-auth package, which has one star).

However, I'm also open to renaming it! I don't think that should hold things up, but there is any consensus around changing the name I'm open to it.

[LoriKarikari]

@ndom91 I just merged my docs before I saw this message lol. It's currently in a docs folder. Can change it if you want.

[iaincollins]

I would vote for keeping ./docs/* as just for Markdown docs, and creating another directory (e.g. /www?) for the website.

If it's not possible to handle this easily in config an okay for making a build step that does something like copies the docs into www/docs (e.g. in a build or dist directory).

[LoriKarikari]

@iaincollins ooh, I was too fast merging that. Sorry about that!

[ndom91]

Yeah it seems they have to be in docs subdirectory.

You could just rename the first /docs folder www so that its /www/docs/content1.md, for example. That way we can skip a build step. The docs subfolder just wont be at the root of the project, I dont know how much of a problem that is for you guys.

[ndom91]

Also just FYI, regarding the build step for building docusaurus, heres the docs from them and an example github action I found:

• https://v2.docusaurus.io/docs/deployment/#deploying-to-github-pages
• https://github.com/clay/docusaurus-github-action

[iaincollins]

@LoriKarikari No worries. :-)

You could just rename the first /docs folder www so that its /www/docs/content1.md, for example. That way we can skip a build step. The docs subfolder just wont be at the root of the project, I dont know how much of a problem that is for you guys.

Oh cool, okay I might do that as I think it's slightly nicer.

I would love to have /docs at the root (as that's what GitHub Pages looks for it seems) but actually if there is a great website, maybe that doesn't matter so much.

Let me know if I should do anything with GitHub pages on the repo! (I will try and figure it out now. :)

I am going to copy current master in to v1 and then merge the v2 branch to be master, so we can all just work off that. :-)

[LoriKarikari]

So it's only the /www/docs folder then?

[ndom91]

Okay I'll hold off on any further changes, etc. until the whole master -> v1 && v2 -> master is complete.

Until then I'll do some research about how to most easily get this into github pages.

[ndom91]

Okay after some further reading, teams is in fact not free haha. Sorry for all the confusion guys.

@iaincollins I would still recommend you put it up on your personal now.sh account though if you dont feel comfortable giving me rights to this repo. Its so easy with now.sh and the whole next-auth part of it just makes sense :)

Or if your cool with it, the other option is I can do it via a mirror of your repo. Its basically no extra work on my side and is transparently up-to-date with your repo, when you push, now.sh updates.

So to wrap up, deploying we have three options:

1) You give me rights to this repo and I deploy via Vercel directly from the repo
2) You make a vercel account and do that yourself
3) I can deploy via my vercel account via a mirror of your repo

[iaincollins]

@ndom91 Thanks, this is helpful! I am not sure the best way to do it but think this is important so appreciate you investigating! I'll add you as a contributor so you can make changes.

(As this is a personal repo and not an organisation one, I'm not sure if it will give you all the access you need for this, but will do that now and see how it goes! If you are missing access to anything after having contributor permissions just let me know and happy to make those changes!)

[ndom91]

Okay great, thanks! I think contributor permissions should be enough

[ndom91]

Damn it.. So without an Organisation there doesnt seem to be a way for me to do it :disappointed:

I tried the mirror variant, but it in fact does not update automatically. Netlify is the same deal - organisations only. I can send you the settings I used for now.sh if you're up for doing it yourself, it wasn't very difficult.

EDIT: Here's the now.sh settings:

You just have to go to add from github repo, select the repo, then it will ask you about the root directory and the build command, etc. and you should be good to go.

[ndom91]

Let me know if thats the route you want to go. That way I will delete my project named next-auth-docs so that you can take that name and our js.org PR will still be valid ;)

[LoriKarikari]

Sucks that the org is taken 😢

[ndom91]

Yeah :cry:

Oh well, I just deleted the now.sh project. If you create it with the name next-auth-docs it will be good to go and then we can still all collaborate inside this github project. The now.sh thing will update automatically with every push once its setup once.

[ndom91]

@iaincollins @LoriKarikari I merged our latest changes to the docs site into master, unfortunately it can't deploy to https://next-auth-docs.now.sh yet since the next-auth.js.org CNAME still isn't updated by those folks.

Until then though, here are the two latest preview URLs:

• https://next-auth-docs-git-add-auth0.iaincollins.now.sh/
• https://next-auth-docs-git-docs-update-1.iaincollins.now.sh/

And thats all for me for tonight. Thanks a lot guys and girls!

[LoriKarikari]

@ndom91 it's enough for me too haha. Night night!

[LoriKarikari]

The documentation site is up and running now.