Skip to content

Remove hard-coded HTML/CSS from index.md #97

Closed

Description

@bvaughn

(This is a tech debt clean-up issue from the legacy Jekyll docs site.)

The docs/index.md file currently contains a lot of HTML- complete with attributes and class names. This file should contain only (or at least predominantly) markdown syntax. We should remove as much of the HTML as possible and instead convert it to regular markdown.

There are 2 things to be aware of while cleaning up this markdown file:

  1. The layout of the home page uses horizontal scrolling for the top section. This is not achievable with regular markdown.
  2. The bottom sections each have a live code example that ties into the home.js template (see below).

The templates/home.js template makes this situation a little more complex, since it currently uses some of the inline HTML elements from index.md to mount examples (eg <div id="helloExample"></div>). It might be acceptable to leave only these mount nodes in the file and remove all else.

It might also be nice to break index down into a couple of files, although this would also require:

  1. Moving home.js from templates to pages and creating a graphql query to load these files
  2. Updating gatsby-node.js to ignore the files (so they aren't turned into standalone pages. (We have a similar check for the error decoder page.)

Making Home a page instead of a template would also provide a nice solution for the horizontal scrolling problem mentioned above.

Also, mountCodeExample currently does some really hacky stuff. Making Home a page instead of a template could help us move some of that hackiness out and simplify things like showing a placeholder while pre-loading Babel (#2).

Please feel free to chat with @bvaughn if you decide to pick up this issue.

Activity

  1. yangshun commented on Oct 9, 2017

    @yangshun
    Contributor

    @bvaughn I would like to take up this task

  2. bvaughn commented on Oct 9, 2017

    @bvaughn
    ContributorAuthor

    This issue is all yours! 😄

    I've added an "in-progress" label so that others will know not to start work on the issue. If you change your mind about the issue, no worries! Just let me know so that I can remove the label and free it up for someone else to claim.

    Cheers!

  3. bvaughn commented on Oct 11, 2017

    @bvaughn
    ContributorAuthor

    Note that PR #100 may have some impact on your work-in-progress @yangshun. Just an FYI.

    I also updated the description to call out the hackiness in mountCodeExample more explicitly.

  4. yangshun commented on Oct 12, 2017

    @yangshun
    Contributor

    Got it. Thanks for the heads up!

  5. bvaughn commented on Nov 7, 2017

    @bvaughn
    ContributorAuthor

    This issue has been resolved via #150 and some follow up commits. Thanks again to @yangshun for your help!

  6. yangshun commented on Nov 7, 2017

    @yangshun
    Contributor

    You're welcome! Sorry this took so long too 😓 Thanks for the follow up work (which made up the bulk of the PR actually 😂 )

  7. bvaughn commented on Nov 7, 2017

    @bvaughn
    ContributorAuthor

    No problem 😁 I'm pretty happy with the resulting solution so yay for us

  8. added a commit that references this issue on Jul 1, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions