WIP new Gatsby Documentation Website fixes #3296

[KyleAMathews]

Heya folks! Did some initial work on getting the new Keystone docs website running to kick off the conversation about that. Lemme know what you think plus report any bugs you see.

Check it out at https://advisor-otter-67205.netlify.com/

We discussed offline hosting the site on Netlify. Once that's going then we'll have continuous deployment of the site going from all pushes to Github.

[bassjacob]

Hey 😄

I think it looks pretty great. Feels very smooth and responsive.

Not sure if it's a bug, or just my browser, but the menu area feels a little constrained, esp with the non-functional scrollbars present?

I'm on a 15 inch screen at 1920*1080, and it feels a little pinched, but again, that might just be my machine.

Feature request wise, what do you think about linking headings on the page as well as other pages?

[KyleAMathews]

@bassjacob what OS/browser are you using? The scrollbars don't show up on my machine. Haven't tested it on non-mac/non-chrome yet.

[bassjacob]

Archlinux and chrome, but all sorts of customisation, so if it's not showing up for you, it's very possibly something on my end.

If I change overflow: scroll to overflow: hidden on the sidebar nav it removes them, but that obviously isn't a solution here 😛

[jstockwin]

Hey, this looks awesome, thanks!

I'm having the same issue with the scrollbars as Jacob, using Windows 10. Happens in Chrome, Firefox and Edge.

It also looks like you've got quite a few linting errors, which is why the build fails. Whatever you're working in has changed tabs to spaces, for example. eslint . --fix might sort out a fair amount of these if you're lucky.

[KyleAMathews]

Hmmm interesting ok.

…

On Wed, Feb 8, 2017 at 12:11 AM Jacob Bass ***@***.***> wrote: Archlinux and chrome, but all sorts of customisation, so if it's not showing up for you, it's very possibly something on my end. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <keystonejs/keystone#3978 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAEVh0McALMpmqOqPKFfK_zmEU_WX015ks5raXjBgaJpZM4L6XmN> .

[KyleAMathews]

Pushed a change which the internetz tells me which fix the scrollbars issue (use only overflow-y and add padding-right). Let me know if things are working! I'll fix the linting issue later.

[jstockwin]

For me you've fixed the horizontal scroll bar at the bottom, but not the vertical one along the side.

[KyleAMathews]

Instead of using display: fixed; overflow-y: scroll, I switched to using react-stickynode which does some fancy stuff to make a nice working sticky node. Things look good now?

https://advisor-otter-67205.netlify.com/guides/how-to-send-emails/

[jstockwin]

Yeah, that's worked, LGTM.

[KyleAMathews]

@bassjacob oh just noticed your comment on linking headers — that's already done (or should be) — the headers only show up when hovering like on Github.

[Noviny]

@KyleAMathews Super excited to see this coming along!

Just wanted to make sure you knew, all the docs from the old website have already been markdownified over here: https://github.com/keystonejs/keystone/tree/website-doc-conversion/docs/website

If you want, I'm happy to work to make these usable for you as part of this 🙂

[KyleAMathews]

@Noviny hey great! Perhaps just cherry-pick your commit into my branch?

[KyleAMathews]

Or is there more work needed to make these pages usable?

[Noviny]

@KyleAMathews The docs need updating, but I'd rather have them in here, and then PR changes into this branch as a single source of docs.

[Noviny]

@KyleAMathews actually, I might update those docs and make a PR into your branch, if that's alright with you.

[KyleAMathews]

Sounds great!

…

On Sun, Feb 19, 2017, 6:10 PM Ben Conolly ***@***.***> wrote: @KyleAMathews <https://github.com/KyleAMathews> actually, I might update those docs and make a PR into your branch, if that's alright with you. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <keystonejs/keystone#3978 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAEVhwGVZ8jBAvl1-B5y5py_-jrM6rAeks5rePX-gaJpZM4L6XmN> .

[Noviny]

@KyleAMathews Just wondering how easy it would be to pull in the field type documentation from where it currently is in the repo.

Currently each field has its documentation in fields/types/{typename}/readme.md, and it would be great to pull the field types and links to them out into the sidebar, but wasn't sure if there was an easy way forward with where they're currently located.

[KyleAMathews]

@Noviny very straightforward — this is exactly what I'm doing with the WIP gatsby website for the various gatsby plugins — http://gatsbyjs.netlify.com/docs/plugins/

[KyleAMathews]

Just added two new Gatsby plugins to the site, gatsby-plugin-offline, and gatsby-plugin-manifest. With these, the site now works offline! Kinda fun/useful for a docs site.

https://advisor-otter-67205.netlify.com/

[KyleAMathews]

Thanks @Noviny for the PR! Merged and pushed the changes to the test website. It brought over documentation from the old site plus we're now pulling in READMEs from the fields.

Note that if you've opened the new site since I added service workers, you'll have to load the site, close the tab, and then open it again to see the changes. I'm planning on adding in the future a toaster that pops up whenever a new update has loaded.

Also it looks like stickynode is a bit buggy with a longer menu.

https://advisor-otter-67205.netlify.com/

[KyleAMathews]

@Noviny I just noticed that since field pages are missing their title (since they don't have frontmatter). One solution would be to add heading { value } to the query to get the first header and then use that to set the title. If that turns out to be the best solution, I could add a limit argument to heading so we don't have to get every heading.

[Noviny]

@KyleAMathews I was actually thinking of adding frontmatter to all the fields for ease of use, as well as some fields are being deprecated, and it would be good to be able to drop them to a second list, rather than the main list with a flag in the docs, which I assume would go in the frontmatter.

Though speaking of subheadings, we'll probably need to decide if we want to split some of the longer guides up, or whether we want to get nested menu items in the sidebar, such as displaying some of the H2s.

[KyleAMathews]

@Noviny the downside to adding frontmatter to READMEs is it renders weird in Github (plus perhaps NPM). Another option for getting the title plus adding info about whether something is deprecated is to just put that in the package.json. Gatsby can query that info as well.

[Noviny]

@KyleAMathews Ah yeah, the github view. Probably better to grab the h1 then.

[KyleAMathews]

Switched to using react-custom-scrollbars — http://malte-wessel.github.io/react-custom-scrollbars/

This lets us return to just using a fixed scrollable container (far superior UX to stickynode) but by using custom scrollbars, it should auto-hide on windows/linux.

@bassjacob @jstockwin how do things look now? You might need to hard refresh to see the latest version.

https://advisor-otter-67205.netlify.com/

[jstockwin]

@KyleAMathews Looks good to me!

[bassjacob]

@KyleAMathews looks much cleaner!