Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: site build corrections, shared doc scrub, and new content #3215

Merged
merged 14 commits into from
Jun 2, 2020

Conversation

EisenbergEffect
Copy link
Contributor

Description

A collection of updates to the documentation build and content.

Motivation & context

There were a few bugs and omissions in the original docs build setup which needed to be fixed. As part of that work, several documents were more correctly integrated and cleaned up. Here's a list of what this PR includes:

  • Fixed the prepare-docs script so that it works on both Mac and Windows
  • Enabled the prepare-docs script to copy special markdown files from various locations in the repo, stripping the markdown h1s and merging them with standard yaml metadata. The special docs include: code of conduct, contributing, license, security, and acknowledements.
  • Enabled prepare-docs to filter out specific component docs for components we aren't ready to make public.
  • Fixed a number of async issues in prepare-docs.
  • Added more thorough handling of non-existent directory structures during file copy operations in prepare-docs.
  • Removed the docs temp folder from source control.
  • Broke out the fast-element documentation into its individual pages, fixing code formatting and added admonitions.
  • Wrote the Getting Started and Next Steps articles for fast-element.
  • Wrote the community/join article.
  • Updated the community/contributor-guide article to include machine and tool setup, along with corrections to commands and procedures for web components.
  • Updated the community/writing-documentation article to include basics of markdown and api documentation, along with instructions on how to test documentation locally.
  • Wrote the resources/browser-support article.
  • Wrote the resources/glossary article.
  • Wrote the resources/faq article.

Note: The bulk of the deleted files are the removal of the docs temp folder from source control.

Issue type checklist

  • Chore: A change that does not impact distributed packages.
  • Bug fix: A change that fixes an issue, link to the issue above.
  • New feature: A change that adds functionality.
  • Documentation: Additions or improvements to documentation.

Process & policy checklist

  • I have added tests for my changes.
  • I have tested my changes.
  • I have updated the project documentation to reflect my changes.
  • I have read the CONTRIBUTING documentation and followed the standards for this project.

@EisenbergEffect EisenbergEffect changed the title Users/eisenbergeffect/docs prep docs: site build corrections, shared doc scrub, and new content Jun 2, 2020
import { FASTElement, customElement, attr, html } from '@microsoft/fast-element';

const template = html<NameTag>`
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this template instead leverage semantic HTML rather than DIVs with classes?

?

Avoid scenarios that require you to directly set HTML, especially when the content is coming from an external source. If you must do this, you should always sanitize the HTML.

The best way to accomplish HTML sanitization is to configure [a trusted types policy](https://w3c.github.io/webappsec-trusted-types/dist/spec/) with FASTElement's template engine. FASTElement ensures that all HTML strings pass through the configured policy. Also, by leveraging the platform's trusted types capabilities, you get native enforcement of the policy through CSP headers. Here's an example of how to configure a custom policy to sanitize HTML:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You may want to explain the acronym for CSP.

</div>

<div class="footer"></div>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same templating concern as commented on previously with reliance on divs over semantics.

CONTRIBUTING.md Show resolved Hide resolved
@EisenbergEffect EisenbergEffect merged commit 4c8c868 into master Jun 2, 2020
@EisenbergEffect EisenbergEffect deleted the users/eisenbergeffect/docs-prep branch June 2, 2020 19:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants