Instructions for @rwwagner90

We need a catch all if a user enters an invalid route. For now, the 404 route should redirect to https://emberjs.com/404. Our deployment env requires that we have an in-app 404 route, and we can't just redirect to https://emberjs.com/404

docs

There's an ongoing project to convert shared website things (like headers, footers, etc) into components that can be reused, but in the meantime we copy/paste. The markup should match https://emberjs.com/404 and more or less match the style. Please put any css in a separate file from the rest of the css, so that when components are ready, we just swap it out.

Markup https://github.com/emberjs/website/blob/master/source/404.html.erb
Relevant css: maybe https://github.com/emberjs/website/blob/master/source/stylesheets/pages/404.css.scss

We still have some work to do on importing fonts/typography styling, so if it doesn't look exactly the same, it's ok. If you match the markup of the website, a subsequent PR will make things match.

Our code blocks fail on color contrast tests. Especially the code blocks with diff in them.

To Do:

• copy/paste from css and template
• make styling adjustments
• swap out templates, css, etc with emberjs/website#3157 once it is ready to ship (more copy/paste)
• replace with components from ember-styleguide once they ship

Examples: http://emberguides.stonecircle.io/v2.17.0/models/ http://emberguides.stonecircle.io/v2.17.0/

(Be able to swap back to the old app if something goes wrong)

Currently, the main link in the navbar is directing to the index page of the Guides app. In contrast the legacy Guides point to the emberjs.com project page:

Guides App	Legacy Guides

How to reproduce

• visit https://emberguides.stonecircle.io/release/
• click on the Ember icon on the left side of the website header
  -> the user will be directed to https://emberguides.stonecircle.io/release/

Expected

To preserve the same behaviour as in the legacy Guides the "Home" navigation link should redirect to emberjs.com.

Test Stats:

Browser: Chrome Version 66.0
Domain: https://emberguides.stonecircle.io/

This needs to be done by one of the members of the Learning Team that has access to the Algolia write API key.

Also this will require implementing batching for https://www.npmjs.com/package/ember-cli-deploy-prember-algolia so that it doesn't run out of memory 😂

The patch version in version selector dropdown has been removed in the api docs so as to avoid confusion when patch releases are made on ember/ember-data. We also did away with the v prefix.

We instead used only majorVer.minorVer in dropdown and urls.(eg 3.1, 2.18) We also added route support to allow for old urls with patch versions in them to still resolve to the latest patch version of what was entered. e.g., https://emberjs.com/api/ember/3.1.10/modules/@ember%2Fapplication will still resolve to https://emberjs.com/api/ember/3.1/modules/@ember%2Fapplication.

This will give a sense of familiarity between using guides & api docs.

We need to use showdown-section-groups to wrap each set of paragraphs between a Header tags in a

Simple use case and should be relatively straight forward thanks to #32

Context here: ember-learn/deprecation-app#65

Disclaimer: I'm only reporting this, haven't dug into the cause 😅

old site

new site

This refactor of the guides app started as a Proof of Concept implementation of a "Just Ember" version of the Ember Guides and as a result of discussions on the community slack, I would like to thank everyone in #ember-learn for their patience in answering all my questions.

The main design of this system is that all of the source markdown files are located in https://github.com/ember-learn/guides-source, which is an npm dependency of this app. Those markdown files are compiled into JSON:API using https://github.com/stonecircle/broccoli-static-site-json and the custom adapter reads the static JSON files directly.

This quest issue it to keep track of all the little things that are required to complete the app so that it is ready to replace the current https://guides.emberjs.com site. This list will likely get a lot bigger before it starts to get smaller, but please clone the repo and test it all the feedback we can get is much appreciated.

If any of the following tasks need more explanation please let me know and I will elaborate on a new issue for that task. You can get help on the Ember Community Slack in the #-team-learning channel if you want to help out.

Blocker Tasks

Still to do

• re-implement the search functionality (Issue: #6 Fixed in: #39)
• add hover-over anchorable-toc "link" for headers (Fixed in: #49)
• add "Old Guides" warning to older guides (Issue: #33 Fixed in: #48 )

Done

• ensure guides-source is up to date and each version is in sync with the current guides site
  • v2.15.0 seems to be out of sync (see ember-learn/guides-source#7)
  • v2.14.0 is missing (see ember-learn/guides-source#8)
  • v2.16.0 is missing
  • v2.17.0 is missing (see ember-learn/guides-source#9)
• make sure that removing the versioning ability of images doesn't cause problems for older guides (see #12 and ember-learn/guides-source#11)
• make sure there is a newline between the end of the paragraph and the references of referential style links in guides-source. This causes an issue with the markdown renderer that breaks the link. Alternatively, this could be fixed upstream: https://www.npmjs.com/package/ember-cli-showdown
• fix all cases where there is a newline between ancor and link because this breaks the link e.g. click [here]\n(https://emberjs.com
• fix the anchorable-toc implementation for linking to headers throughout the guides
• fix styles and display of code samples: either implement highlight in Javascript or finish the Prism configuration (see #7)
• fix the indentation on /testing/acceptance for the ### Asynchronous Helpers list
• make sure underscores are escaped properly so they aren't interpreted as italics markdown e.g. **node_modules / package.json** on /tutorial/ember-cli.md
• prevent ... from being replaces with an ellipsis e.g. ...arguments on /object-model/classes-and-instances.md
• fix the chapter links for the very last page i.e. on the /glossary/web-development page it shouldn't say "We've Finished Glossery ... "
• get the table of contents dropdown working on mobile
• upgrade the older versions (v1.10.0) guides.yml to follow the structure of the pages.yml so it will work with the new guides-app (see ember-learn/guides-source#10)
• stop hard-coding the versions and have it consumable from the guides-source - also have 'current version' defined by data from the guides-source (see #9)
• implement 'current' route
• make sure titles are being added as meta-data (See #26)
• fix titles on "index" pages (#27)

Release Tasks

• use prember to pre-render

Extra (nice to have) Tasks

• remove images from guides-source because they are hosted by the app now (did this the other way round)
• (edit un-finished tasks moved to: https://github.com/ember-learn/guides-app/projects/2)

• re-implement the diff system for code highlights
• ensure things like {{outlet}} are still getting highlighted.
• extend prism's diff language to diff + js & diff + hbs

Repro:

1. Navigate to: https://guides.emberjs.com/v1.12.0/nonsense/route/
2. Note that the application doesn't render

Proposed solution:

1. Navigate to: https://guides.emberjs.com/v1.12.0/nonsense/route/
2. Be redirected to https://guides.emberjs.com/v1.12.0/
3. Application renders

If the version also happens to be invalid, we can redirect to /release/ by default, this way at least the application renders something useful.

This is related, but not the same as: #132

Does this potential fix work or would the team prefer a 404, as in the other example?

Fixed by #226

To match API docs, we should use release in the urls to indicated the latest version. However we should still support current so we don't break untold numbers of bookmarks in everything.

To do

• add release
• write some tests

Wishlist for later PRs:

• if you go to the latest version, it replaces the version # with release
• need to start using release in the API docs and guides :x

I wanted to re-instate the Select2 implementation in the new system but https://github.com/iStefo/ember-select-2 is "deprecated in favour of ember-power-select".

We need to re-implement the version picker using http://ember-power-select.com/docs/the-search

@rwwagner90 I assigned this to you because you suggested it and you seemed to understand what is needed to be done 👍

The goal of this whole project is to make things functionally exactly the same and worry about any more general improvements after initial release

To that end we need titles to match current titles, I will point out some examples that may end up being edge cases but if we get these working I will be happy shipping for the initial release.

The general structure seems to be: Ember.js - <section title>: <page title> where:

• section title: is the same as the section in the TOC
• page title: is the same as the H1 at the top of the page

Examples:

• https://guides.emberjs.com/v2.17.0/routing/defining-your-routes/
  • Ember.js - Routing: Defining Your Routes
• https://guides.emberjs.com/v2.17.0/
  • Ember.js - Guides and Tutorials
• https://guides.emberjs.com/v2.17.0/models/
  • Ember.js - Models: Introduction

Those last 2 might be a bit tricky because they play with the index implementation, and that has already caught me a few times at this stage 😖 #27

Fixtures are removed from the guides. I really need it. Otherwise could you please suggest some tutorial to use data from model (same as using fixtures)?

We might be able to get some inspiration here: ember-learn/deprecation-app#56

This happens in Japanese at the moment on a specific condition.

• Firefox 57.0.4 on Mac High Sierra

On the new site, when viewing via mobile and tapping a new link (under the nav header), I currently don’t get that “oh wow it’s fast” feeling @mansona was talking about. That’s due to the fact the nav box stays open on route change, leaving me wondering if anything had happened ...

Works great on other links at the bottom of each page though! 👍

The current engine tag is:

  "engines": {
    "node": "^4.5 || 6.* || >= 7.*"
  },

Recommend we change it to >= 10.* as it's the new LTS and appears to work well.

No version of node lower than 8 will successfully run npm start.

node = v8.15.1 appears to work.

When running node 7.10.1, I get another error message:

  - stack: /Users/ed/Documents/guides-app/node_modules/algolia-html-extractor/lib/algoliaHtmlExtractor.js:17
      ...options,
      ^^^
SyntaxError: Unexpected token ...
    at createScript (vm.js:53:10)
    at Object.runInThisContext (vm.js:95:10)
    at Module._compile (module.js:543:28)
    at Object.Module._extensions..js (module.js:580:10)
    at Module.load (module.js:488:32)
    at tryModuleLoad (module.js:447:12)
    at Function.Module._load (module.js:439:3)
    at Module.require (module.js:498:17)
    at require (internal/module.js:20:19)
    at Object.<anonymous> (/Users/ed/Documents/guides-app/node_modules/algolia-html-extractor/index.js:1:92)

When using node 6.17 and attempting to run ember serve I get the following error message:

  - stack: /Users/ed/Documents/guides-app/node_modules/ember-cli-deploy-prember-algolia/index.js:58
      upload: async function(context) {
                    ^^^^^^^^

SyntaxError: Unexpected token function
    at createScript (vm.js:56:10)
    at Object.runInThisContext (vm.js:97:10)
    at Module._compile (module.js:549:28)
    at Object.Module._extensions..js (module.js:586:10)
    at Module.load (module.js:494:32)
    at tryModuleLoad (module.js:453:12)
    at Function.Module._load (module.js:445:3)
    at Module.require (module.js:504:17)
    at require (internal/module.js:20:19)
    at PackageInfo.getAddonConstructor (/Users/ed/Documents/guides-app/node_modules/ember-cli/lib/models/package-info-cache/package-info.js:380:18)

It's fair to assume that anything less than 6 also doesn't work from these error messages.

Current

Currently, there are sections (which can be found in older versions of the Guides but which have been deprecated in newer release versions) which contain a link to see the same section in the most recent version of the app. Some of these links are broken and clicking those elements will raise errors in the app. E.g.

Error while processing route: version.show Ember Data Request GET /content/v3.1.0/controllers/representing-a-single-model-with-objectcontroller/index.json returned a 404
Payload (Empty Content-Type)

See also e.g.:

Guides App	Legacy Guides

The Legacy Guides seem to circumvent this issue by not providing links which point to the corresponding chapter in the current Guides version on deprecated chapter pages.

How to reproduce

• visit https://emberguides.stonecircle.io/v1.10.0/controllers/representing-a-single-model-with-objectcontroller/
• click the "View 3.1" link in the upper right corner

Expected

• the link to the new Guides version does either not show up in the first place for sections that don't exist anymore in newer versions of the Guides or the link points to one of the parent chapters instead

Test Stats:

Browser: Chrome Version 66.0
Domain: https://emberguides.stonecircle.io/

We should ignore anything to do with CSS, as it will be addressed when we merge in Mel's new styling

I'm trying to clarify if we only want guides results when searching on https://guides.emberjs.com/

I seem to remember that there were some discussions that this is expected behaviour i.e. that you cannot search for API results when you're on the guides. I'm not saying it's the desired behaviour (I know we want to unify all of this) but I'm under the impression that we are expecting it to work this way right now.

Please note: that we need to move the "Edit Page" link out of the Header in the markup but the location should not change. This will need some work on CSS too 👍

This is for both Accessibility (i have a feeling that it might be read out by a screen reader) and for the search index. Currently when you index the Guides every top-level title will have the words "edit page" in them 😖

Is multilingual support on the roadmap? The translations themselves are probably harder to pull off than the technical implementation, but I think it's a worthwhile long-term goal.

Probably related to #57.

On https://www.emberjs.com/, the “view quick start guide” link goes to https://guides.emberjs.com/current/getting-started/quick-start/ which is a 404; it should be https://guides.emberjs.com/release/getting-started/quick-start/ instead.

If the link was always broken, it should just be fixed; but presuming that it worked once upon a time, a redirect should be added so that /current/* goes to /release/*.

When the primary call to action from the home page is a broken link, a very bad impression is left!

Need to document some more things if we're going to launch and/or use this in the contributors' workshop

(other maintainers are welcome to edit this directly)

• recent-ish guides nav by previous-next links
• cookbook nav by previous-next links
• navigation by TOC
• navigation by dropdown
• current url works

Helps with #4

I just started extracting the necessary search components from ember-api-docs into a separate Ember add-on so that we can share those components between this app and ember-api-docs.

An initial WIP PR is up at ember-learn/ember-learn-search-components#1, but when that is done, we'll want to use those components in this app

Current

Currently the Edit on Github link on the index page doesn't link to the correct file on Github:

How to reproduce:

• visit https://emberguides.stonecircle.io/release/
• click pencil icon in upper right corner
  -> the user is redirected to https://github.com/ember-learn/guides-source/edit/master/guides/v3.1.0/index/.md

Expected

• if the user clicks the pencil icon in the upper right corner of the index page, they will be redirected to https://github.com/ember-learn/guides-source/edit/master/guides/v3.1.0/index.md

Test stats:

Browser: Safari Version 11.1
Domain: https://emberguides.stonecircle.io

Essentially we need to revert this #59 after the final testing phase is complete

Current

Currently the dropdown list below the guides search is always shown, even if the search query is empty. See also in comparison to the UI of the legacy guides:

Guides App	Legacy Guides

|

How to reproduce:

• visit https://ember-guides-prod.herokuapp.com/release/
• enter a query into the search field in the nav bar in the upper right corner
• delete the query entirely

Expected

The dropdown list below the search field is hidden once the search query is empty

Test stats:

Browser: Safari Version 11.1
Domain: https://ember-guides-prod.herokuapp.com/release/