Discussion: do we want to continue using Jekyll?

[kaicataldo]

Some of this was discussed previously on this PR.

As we go through the process of redesigning our site, it seems like another good opportunity to re-evaluate whether we want to:

1. Stick with Jekyll
2. Add a build step for the demo

Pros to switching to a JS-based site generator:

• It would allow us to dog food ESLint in a more modern web application
• It could open the door to more contributions from the community since the build tool would be in a language our users are a familiar with
• We get to start using npm and its ecosystem for package management, making it easier to update/change packages and improve things in the future (i.e. things like switching out the code editor package, rewriting in another framework, etc. all become much easier to implement)
• Increased performance for interactive elements (the demo, for instance, has a pretty long period of time to interaction)

Cons:

• We would be adding the complexity of a build step (GitHub pages handles this for us now, since we're using Jekyll)
• There will be time/effort needed up front to convert the existing site over to another site generator

Even if we do decide to stick with Jekyll, I would still be a proponent of bundling/building the JS we have, for the reasons listed above.

Note that both Babel and Vue.js have build steps, and it seems to be working for them! Vue.js's deployment strategy sounds pretty appealing to me:

The site is automatically deployed when commits land in master, via Netlify.

If we had a system like this in place, it seems like we wouldn't ever have to worry about running the build locally or for it getting out of sync (which I know were concerns before).

For reference, Babel and Prettier use Docusaurus, and Vue.js uses Hexo.

One very interesting benefit to Docusaurus is that it has the ability to create versioned docs out of the box.

I would be willing to work (even if it's just exploratory) on this!

[g-plane]

For my personal opinion, I prefer VuePress, but I'm not opposed to using other CMS.

[not-an-aardvark]

I don't have any strong feelings about our site generator. I'm fine with switching to another generator/adding a build step if it makes things easier.

[ilyavolodin]

I absolutely hate Jekyll - because Ruby on Windows is just a nightmare. But at the same time, I just don't see the point in adding complicity for what I perceive - minimal gains.

[j-f1]

Netlify has been pretty awesome in my experience. If you were to move the website to the main ESLint repo, you’d be able to run the demo on PRs to test out changes to the core.

[btmills]

I’ll admit to having been occasionally reluctant to work on the site because I’d first have to get Jekyll working locally. I don’t see that by itself as sufficient reason to switch, but it certainly makes the idea more appealing. I didn’t know that Docusaurus gives versioned docs for free. We’ve talked about ways to accomplish that before, and I’ve seen questions e.g. on Stack Overflow where someone was trying to use a feature that was in the docs but not their version. That could be a big win.

[nzakas]

I'm still a big fan of Jekyll. I use it for my personal site and have figured out a bunch of ways to make things less painful that I'd happily migrate to the ESLint site. My site is running on Jekyll + Netlify and I kind of love it. :) For the demo, in particular, I think it might be worth splitting that out into its own app with its own build system (and host at demo.eslint.org). We definitely need to figure out how to deal with versioning the docs, though. My biggest concern about switching to anything is that I wouldn't want the documentation site to be dependent on people knowing React, Vue, or any other client-side framework. I'm afraid that would make it harder for more casual developers (and designers) to contribute meaningfully.

…

On Tue, Feb 5, 2019 at 5:29 AM Brandon Mills ***@***.***> wrote: I’ll admit to having been occasionally reluctant to work on the site because I’d first have to get Jekyll working locally. I don’t see that by itself as sufficient reason to switch, but it certainly makes the idea more appealing. I didn’t know that Docusaurus gives versioned docs for free. We’ve talked about ways to accomplish that before, and I’ve seen questions e.g. on Stack Overflow where someone was trying to use a feature that was in the docs but not their version. That could be a big win. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#536 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AACWkp6OTCz2_-p1Sw5edS-xTqZUjMHrks5vKYcxgaJpZM4ah9X6> .

--

______________________________ Nicholas C. Zakas @SlickNet Author, Principles of Object-Oriented JavaScript <http://amzn.to/29Pmfrm> Author, Understanding ECMAScript 6 <http://amzn.to/29K1mIy>

[g-plane]

@mysticatea has his own demo site.

[mysticatea]

@g-plane Thank you for the mention.

I don't like Jekyll because that experience on Windows is terrible. I'm happy if we decide to use a JS-based site generator.

I have some plugins which are hosted with a JS-based site generator, VuePress.

• https://vuejs.github.io/eslint-plugin-vue/
• https://mysticatea.github.io/eslint-plugin-eslint-comments/
• https://mysticatea.github.io/eslint-plugin-es/

Those sites have interactive examples to know how the rule reports code. For example https://vuejs.github.io/eslint-plugin-vue/rules/no-dupe-keys.html

The experience with VuePress is nice to me.
Basically, we don't need additional knowledge about Vue.js. We can write sites with Markdown files. Additionally, we can use Vue.js components to enhance Markdown files. This is additive.
As a result, we can write the interactive example very easily; only wrapping a code block by <eslint-code-block> tag in Markdown. <eslint-code-block> tag becomes an intaractive editor because it's a registered Vue.js component. For example:

<eslint-code-block :rules="{'vue/no-dupe-keys': ['error']}">

```vue
<!-- write example code here -->
\```

</eslint-code-block>

https://raw.githubusercontent.com/vuejs/eslint-plugin-vue/master/docs/rules/no-dupe-keys.md

And I have some online demo site.

• Vue.js plugin's ... https://mysticatea.github.io/vue-eslint-demo/
• TypeScript plugin's (WIP) ... https://mysticatea.github.io/typescript-eslint-demo/

Also, I have been maintaining some packages to help to build such documentation and online demo.

• eslint4b ... An ESLint build that works in browsers
• vue-eslint-editor ... An interactive editor that runs ESLint in VSCode editor

All of above documentations and online demos are built with eslint4b and vue-eslint-editor.

[nzakas]

Very interesting, thanks for explaining. Given that Vue components are additive and not required, then I'm not opposed to investigating Vuepress.

…

On Tue, Feb 5, 2019 at 9:02 PM Toru Nagashima ***@***.***> wrote: @g-plane <https://github.com/g-plane> Thank you for the mention. I don't like Jekyll because that experience on Windows is terrible. I'm happy if we decide to use a JS-based site generator. I have some plugins which are hosted with a JS-based site generator, VuePress <https://vuepress.vuejs.org/>. - https://vuejs.github.io/eslint-plugin-vue/ - https://mysticatea.github.io/eslint-plugin-eslint-comments/ - https://mysticatea.github.io/eslint-plugin-es/ Those sites have interactive examples to know how the rule reports code. For example https://vuejs.github.io/eslint-plugin-vue/rules/no-dupe-keys.html The experience with VuePress <https://vuepress.vuejs.org/> is nice to me. Basically, we don't need additional knowledge about Vue.js. We can write sites with Markdown files. Additionally, we can use Vue.js components to enhance Markdown files. This is additive. As a result, we can write the interactive example very easily; only wrapping a code block by <eslint-code-block> tag in Markdown. <eslint-code-block> tag becomes an intaractive editor because it's a registered Vue.js component. For example: <eslint-code-block :rules="{'vue/no-dupe-keys': ['error']}"> ```vue<!-- write example code here --> \``` </eslint-code-block> https://raw.githubusercontent.com/vuejs/eslint-plugin-vue/master/docs/rules/no-dupe-keys.md And I have some online demo site. - Vue.js plugin's ... https://mysticatea.github.io/vue-eslint-demo/ - TypeScript plugin's (WIP) ... https://mysticatea.github.io/typescript-eslint-demo/ Also, I have been maintaining some packages to help to build such documentation and online demo. - eslint4b <https://www.npmjs.com/package/eslint4b> ... An ESLint build that works in browsers - vue-eslint-editor <https://www.npmjs.com/package/vue-eslint-editor> ... An interactive editor that runs ESLint in VSCode editor All of above documentations and online demos are built with eslint4b <https://www.npmjs.com/package/eslint4b> and vue-eslint-editor <https://www.npmjs.com/package/vue-eslint-editor>. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#536 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AACWkpqagRwLE7FVSHVDIEfKmk2Ni2CPks5vKmHqgaJpZM4ah9X6> .

--

______________________________ Nicholas C. Zakas @SlickNet Author, Principles of Object-Oriented JavaScript <http://amzn.to/29Pmfrm> Author, Understanding ECMAScript 6 <http://amzn.to/29K1mIy>

[kaicataldo]

For what it's worth, other popular static site generators like Gatsby and Docusaurus also allow you to create pages using Markdown as well.

@nzakas Would it possible to share how you've made working with Jekyll fit your workflow better?

Edit: Better link for the Docusaurus Markdown workflow.

[nzakas]

Sure! I think for me the big thing was just installed Jekyll with bundler to install and run it. We already point to the docs on how to do that in the README: https://help.github.com/articles/setting-up-your-github-pages-site-locally-with-jekyll/ I also found this helpful: https://cloudcannon.com/tips/2017/12/08/speed-up-your-jekyll-builds/ Then I made a fast dev build that omitted everything I didn't usually need during development. I'm not sure what other problems people on Windows are referring to, but let me know.

…

On Wed, Feb 6, 2019 at 1:45 PM Kai Cataldo ***@***.***> wrote: For what it's worth, other popular static site generators like Gatsby <https://www.gatsbyjs.org/docs/adding-markdown-pages/> and Docusaurus <https://docusaurus.io/docs/en/doc-markdown> also allow you to create pages using Markdown as well. @nzakas <https://github.com/nzakas> Would it possible to share how you've made working with Jekyll fit your workflow better? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#536 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AACWku9OYicyP7TruFsPxNTzbjBtraa4ks5vK0zpgaJpZM4ah9X6> .

--

______________________________ Nicholas C. Zakas @SlickNet Author, Principles of Object-Oriented JavaScript <http://amzn.to/29Pmfrm> Author, Understanding ECMAScript 6 <http://amzn.to/29K1mIy>

[g-plane]

What's the progress?

[nzakas]

I don't think we've assigned this as an action item to anyone at this point. Does anyone want to volunteer to look at Vuepress and provide feedback? One thing I noticed when I checked it out is that it doesn't appear to have blog functionality built-in. We rely on the ESLint blog a lot, so that's important for us to consider. We could always run Jekyll just for the blog and Vuepress for everything, but it would be nice to know if I missed something here.

…

On Sat, Mar 2, 2019 at 8:07 PM Pig Fang ***@***.***> wrote: What's the progress? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#536 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AACWkibFp_c8J-MVjXwVl7FwJyu9qnWiks5vS0qXgaJpZM4ah9X6> .

--

______________________________ Nicholas C. Zakas @SlickNet Author, Principles of Object-Oriented JavaScript <http://amzn.to/29Pmfrm> Author, Understanding ECMAScript 6 <http://amzn.to/29K1mIy>

[g-plane]

Currently, VuePress doesn't support blog officially, but there are implementations by community. And blog will be supported officially in their next major version.

We could always run Jekyll just for the blog and Vuepress for everything.

@nzakas It's a good idea!

[kaicataldo]

I might have some time to look at this in the next few weeks. It sounds like there are a few of us interested in VuePress. I still think Docusaurus seems like a better option, for the following reasons:

Docusaurus builds the site from markdown files (with the ability to custom pages as React components for things like the demo), has the ability to create blogs, and supports Alogolia search out of the box. This Babel issue seems to indicate that migrating from Jekyll to Docusaurus is relatively painless.

It also looks like VuePress is currently in alpha and doesn't guarantee stability at the moment, and I'd also lean towards using something that is tried and true like Gatsby in the event we decide not to use Docusaurus.

As far as having a build/publish step goes, there are some solutions listed in the official docs. Also of note: if Netlify seems like a better option than setting up our own CI build step, they do offer a free plan for teams maintaining open source projects.

Looking forward to hearing what you all think!

[kaicataldo]

I seem to have forgotten to list what I think is the most compelling reason to use Docusaurus - versioned docs! If we decided to go that route, I think we should start by creating versioned docs for releases going forward (we would have to decide if we want to run it on all releases, or limit it to major and minor releases) and leave the existing old major versioned docs in a more visible place. We could look into trying to somehow extracting old versions, but I'm not sure it's worth the effort at this point.

[platinumazure]

I seem to have forgotten to list what I think is the most compelling reason to use Docusaurus - versioned docs!

Yes!

Does Docusaurus also let us annotate when a particular feature (e.g., a rule option) is added somehow?

[kaicataldo]

Does Docusaurus also let us annotate when a particular feature (e.g., a rule option) is added somehow?

It doesn't look like Docusaurus has that functionality built in. It looks like running the docusaurus-version command saves the current site into a versioned doc directory (see the Babel website's repo for an example).

[j-f1]

Prettier’s website uses Docusaurus’s versioned docs: https://prettier.io/versions.html. What would likely happen is that the latest (“master”) version of the docs would be pulled from the ESLint repo at build time, but the old versions would live here in a versioned_docs directory.

[kaicataldo]

I spent some time with Docusaurus and wanted to report my findings.

Docusaurus is a lot more opinionated than I had originally thought. I don't believe the limitations I've found need to be blockers, but they do make it more difficult to cut over the site as it is currently designed.

• I didn't realize that Docusaurus uses React only as a rendering engine at build time, meaning that it can only generate static markup. It's possible to add interaction, but it's done by including a script tag in a page template (see https://github.com/babel/website/blob/master/website/pages/en/repl.js for an example).

• Docusaurus handles the general layout and styles. It's possible to add your own custom CSS, but much of the layout and markup is generated by Docusaurus, limiting the extent to which you can customize things.

• Dropdowns are not supported in the navigation header.

The first two of these issues seem to be items the maintainers have on their roadmap, but I'm not sure of the timeline on that.

These limitations are an issue with the site as it is currently designed. That being said, I don't think they would be an issue for the newly designed site, as it happens to match the layout generated by Docusaurus.

Edit: I'm not entirely sure how we should move forward. Part of me thinks it would still be worth switching over to Docusaurus (and making compromises/design around the limitations) because:

• So many other open source projects are using it and we get to benefit from the community around it
• Docusaurus is a tool that's dedicated to solving this specific problem
• We know that it's being actively developed (and supported by Facebook) and that we'll be able to benefit from future features coming down the pipeline

[kaicataldo]

Moved this comment into its own issue so it could be evaluated as a separate proposal. #576

[kaicataldo]

Now that the work for #576 is done, we are in a position to use any static site framework we'd like!

Have people's opinons changed? There have been mentions of Vuepress, Gatsby, and Docusaurus. I'm still of the mind that using Docusaurus is a win in the long run, since we get to take advantage of the community around that project and since the problem is trying to solve is open source documentation, but I'm definitely open to exploring other options.

[kaicataldo]

Would love to continue moving this discussion forward.

What framework should we use?

I'm currently using Gatsby to build my personal website and no longer think it's a good idea for our use-case here. While I've really been enjoying using it, I think there's just too much overhead with having to understand React, how to correctly write components to work with server-side rendering, GraphQL, and the framework itself. It's a really powerful, flexible tool that gives you a lot of options, but I don't think it meets our desire to have a website that is easy to contribute to. Docusaurus feels like a better option in this regard, but it also might be too rigid for our use case and would still have some of the same downsides Gatsby has regarding React and SSR.

I'm not sure how Vue-powered alternatives compare in this regard (maybe @mysticatea would have some insight), but @nzakas pointed me to Eleventy a while back, and it does seem like a framework with a much lower barrier to entry. It should also be fairly easy to convert, as it has a lot of flexibility in terms of what templating engines it allows.

Do we want to tie this to the site redesign?

I don't know if we have to tie this to the site redesign, particularly if we're cutting over to something like Eleventy where we might able reuse a lot of the existing codebase. If we were to cut over to something that would involve rewriting everything into Vue/React components, it might make more sense to do it all at once to minimize churn/throwaway work.

Thoughts?

[nzakas]

I generally agree with your assessment. I looked at a bunch of options and have felt like they were either too complicated (Gatsby, Docusaurus) or not complete enough (Vuepress). It seems like Eleventy is the simplest and most straightforward port of what we have now.

I don’t think we should tie a platform change to a redesign. I’d still like to investigate hiring a designer to do a proper redesign, and I don’t see a reason to create a dependency on that for moving off of Jekyll.

[kaicataldo]

I know we haven't necessarily decided to go this route, but I opened a PR cutting over the site to Eleventy to see how easy it would be here. It was pretty straightforward!

After going through this process, I like Eleventy. I think it has a low barrier to entry and seems to be quite flexible (down to being able to switch out templating engines). I kept things mostly the same for this PR for ease of conversion, but we don't have to stick with a lot of the constraints that Jekyll has if we decide to go this route.

[ilyavolodin]

The site has been migrated from Jekyll to Eleventy, so closing this issue.