Website Plan

[ForbesLindesay]

• [x] Create a separate repo for pug website (pug-www), containing a node.js website
• [x] Create a repo for the English pug documentation (pug-en)

  Infrastructure Tasks

• [x] Add css (less?) and pug (obviously) templating
• [x] Add a browserified JavaScript file
• [x] Style and layout similar to https://facebook.github.io/jest/ using the pug logo and colors from the pug logo
• [x] Pull content from either ../pug-en on local file system or https://github.com/pugjs/pug-en if that doesn't exist. (We can use gethub to automatically pull it into a local "cache" dir.
• [x] Render content as markdown with embedded React Elements. Render the embedded react elements both server-side and client side.
• [x] Write React component for pug source and output (use https://github.com/ForbesLindesay/react-code-mirror for the editor?). Output should have three modes:
  • JavaScript (use UglifyJS to beautify this)
  • HTML
  • Beautified HTML

    Content Tasks

• [x] convert all current screens into markdown files within pug-en, including embedded react elements for dynamic pug code.

  General Thoughts

What's the best syntax for embedding dynamic/custom elements inside markdown. Is there any prior art on this? We could just use HTML syntax? I don't think we should use pug as it's not really designed for such large blocks of content and may be more painful to translate.

How should we define the examples? It would be cool to have some kind of "file system" mocked out by implementing fs.readdirSync, fs.readFileSync and fs.writeFileSync, that way we could have proper dynamic demos of extends/includes.

Could we use brcdn.org (which I need to fix as it currently keeps running out of memory) to dynamically fetch the relevant jstransformers to make filters work client side? Probably a decent stretch goal but not something for v1.

Can we re-introduce something like the old test page, but extended and made even more awesome:

• It should let you add/remove/edit pug files in a virtual file system
• It should let you define both options and locals using JavaScript syntax
• It should let you see the output of compiling each file in each stage of the process (lexer output, parser output, loader output, linker output, code-gen output, html, beautified html).

  Deployment

I'll write a script to use travis to auto-deploy to amazon S3 as it's faster & more reliable than GitHub pages.

Domain

I intend to host it at pugjs.org as it's more consistent with the rest of our branding, but will make pug-lang.com redirect as people are already starting to hit that domain. Once we have something workable we can redirect jade-lang.com.

[TimothyGu]

What's the best syntax for embedding dynamic/custom elements inside markdown. Is there any prior art on this? We could just use HTML syntax? I don't think we should use pug as it's not really designed for such large blocks of content and may be more painful to translate.

Depends on the use case, and how complex we want to make it, I guess. If it's just a single-file demo like those on the current language syntax pages, then markdown-it has support for a highlight function that seems to make it fairly simple. Just code block syntax would work in this case.

However if it's anything more complex (like the proposed virtual FS), I think we'd have better chances to just use HTML, or easier, move the demo into a separate page.

OTOH, I don't know how this is going to play out with React, as truth be told I have no experiences with it (only with Polymer, where components are literally just HTML).

---

How should we define the examples? It would be cool to have some kind of "file system" mocked out by implementing fs.readdirSync, fs.readFileSync and fs.writeFileSync, that way we could have proper dynamic demos of extends/includes.

It would be, and it doesn't sound too difficult either with pug-load.

---

For the editor itself, we could also adapt AST explorer's React components, if it's too much work to update react-code-mirror.

---

Another idea is perhaps we could integrate GitHub Gist for the FS demo. This way we can use one page for all multi-file demos, and maybe even offer the option to save the user's result of tinkering.

So here's what I would expect from such a page (excuse my drawing):

---

I intend to host it at pugjs.org as it's more consistent with the rest of our branding, but will make pug-lang.com redirect as people are already starting to hit that domain. Once we have something workable we can redirect jade-lang.com.

Have you purchased pugjs.org yet?

[ForbesLindesay]

Just looked at what you did with pug-preview as a syntax highlighting scheme. Looks like a pretty good approach for now. I think we may end up also wanting some way to embed totally arbitrary components, but we can leave that for now.

react-code-mirror should be easy to update, and I'm happy to move it into the pugjs org.

github-gist could be really interesting. I'm hoping we can let people submit issues with a link to our demo page. This would massively improve the quality of pug reports.

Yes, I've purchased the domain.

[MichaelZaporozhets]

@ForbesLindesay Not entirely sure where to put this but I'd love to help develop out a design/implementation.

[TimothyGu]

An update. Things are beginning to look pretty good.

[ForbesLindesay]

This is looking great. I'll get it published this weekend. I think it's good enough for us to make it the primary source of docs and iterate from there.

[TimothyGu]

Website is live! Certain things still haven't been written yet, such as a main page, and a full-fledged demo, but let's move that to pug-www.

[SergioCrisostomo]

:clap: