Docs: new site for docs

[anikethsaha]

Created a site for the docs using docsify

• Site preview : https://espree-site.netlify.com/#/

• Features

  • searching
  • dark mode
  • code highlighting and copy clipboard
  • edit button
  • responsive
  • easy adding of content. (simply add .md file in docs folder and add it to _sidebar.md, that's it)

• docs about usage, about and developer guide can be added smoothly once the content is ready

• about the demo page, as this is mostly a static site having demo might be a tricky one as docsify is no-framework static site generator. It can be done but having no framework demo page might be heavy load. I can give it a shot if time permits 👍

• Screen shots

• 

• 

• 

• 

• Side bar in mobile view :

I couldn't find the logo for espree so I used eslint's logo.
If dark mode is not preferrable, let me know, I will remove the plugin for it

ref #25

PS: it took 8-10 mins (without the deployment step) to create this site. 😁

[nzakas]

Wow, very cool! Thanks for doing this.

Is it possible for you to add a script that will auto run docsify as part of this PR?

[kaicataldo]

Wow, I hadn't heard of Docsify before. This is really cool.

Re the demo, I think we should point people to AST Explorer, since it's an existing, well-maintained tool.

[anikethsaha]

Is it possible for you to add a script that will auto run docsify as part of this PR?

@nzakas I didn't get this. Did you mean having no server to run the script like it can be run in file protocol ?

[anikethsaha]

Wow, I hadn't heard of Docsify before. This is really cool.

Re the demo, I think we should point people to AST Explorer, since it's an existing, well-maintained tool.

Yes, this is better, AST Explorer does have a espree parser as a dedicated option.
I will add a link in the navbar

[anikethsaha]

I added a demo link in the sidebar instead of navbar as it was not looking in small browser width as there is the dark mode and github banner there as well.

@kaicataldo, @nzakas
Let me know if you want any changes

[anikethsaha]

https://espree-site.netlify.com/#/

Will have a preview of the live changes 👍

[kaicataldo]

@nzakas We won’t need a build step because it’s not actually a static site. I believe this works by pointing Netlify to docs/index.html and the site is generated by the docsify script at runtime. I do think we should add docsify-cli as a dependency and to have an npm script for local hosting/development.

@anikethsaha Is this published under your own personal account on Netlify? If so, would you be willing to transfer it to the ESLint organization so that we can maintain it going forward? This would allow us to add a custom domain as well (even if it’s just a subdomain of eslint.org).

Regarding the AST Explorer link, I wonder if we should add this to the home page with an explanation of what AST Explorer is instead? I think having an external link without an explanation will be confusing.

[anikethsaha]

@nzakas We won’t need a build step because it’s not actually a static site. I believe this works by pointing Netlify to docs/index.html and the site is generated by the docsify script at runtime.

yes, everything here is the runtime

I do think we should add docsify-cli as a dependency and to have an npm script for local hosting/development.

@kaicataldo docsify-cli needs to be installed as a global dep. We don't need this in order to host it.
consider docsify as no-framework js script. we actually dont need any build step. for local development, you can use the cli or any other server just to serve the docs folder

@anikethsaha Is this published under your own personal account on Netlify? If so, would you be willing to transfer it to the ESLint organization so that we can maintain it going forward? This would allow us to add a custom domain as well (even if it’s just a subdomain of eslint.org).

yes, it's under my personal account. I can transfer the account or if you want I will delete this site and you can simply point the publish directory in netlify to docs dir and that's it.
let me know which is fine by you 👍

Regarding the AST Explorer link, I wonder if we should add this to the home page with an explanation of what AST Explorer is instead? I think having an external link without an explanation will be confusing.

yes it makes sense, can you share what kind of explanation I need to add cause I think it may be something about the what are ASTs, and how we can get AST in espree ?

[nzakas]

Ah okay, I totally misunderstood what was happening here. Thanks for explaining.

I think we should be able to set up our own Netlify site to use this. Maybe we can use espree.eslint.org?

[kaicataldo]

yes it makes sense, can you share what kind of explanation I need to add cause I think it may be something about the what are ASTs, and how we can get AST in espree ?

We should probably rethink our documentation since it's so incomplete, but I think it makes sense to have a short section about AST Explorer and how it can be used to visualize the AST in the AST section of the docs. As I think about this more, I actually think we should just merge this as-is so that we can get our Netlify site set up and then iterate on it from there.

[kaicataldo]

One small comment above but otherwise this LGTM.

[kaicataldo]

I think we should merge this as-is and iterate from there. Once we get it merged I can set up the Netlify site.

[kaicataldo]

Thanks for doing this!

[nzakas]

Agreed. Merge + iterate is the way to go.

[anikethsaha]

thanks for the quick review.
Let me know if you need anything over the iteration 👍

[kaicataldo]

This site is now live at https://espree.netlify.com.