Skip to content

Commit

Permalink
Update boilerplate files after move to Docusaurus
Browse files Browse the repository at this point in the history
  • Loading branch information
@JoelMarcey
JoelMarcey committed May 24, 2018
1 parent b31999f commit 2c59657
Show file tree
Hide file tree
Showing 4 changed files with 45 additions and 175 deletions.
2 changes: 2 additions & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,4 +18,6 @@ website/build/
website/yarn.lock
website/node_modules
website/i18n/*
website/package-lock.json
website/yarn-error.log
!website/i18n/en.json
3 changes: 3 additions & 0 deletions CODE_OF_CONDUCT.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Code of Conduct

Facebook has adopted a Code of Conduct that we expect project participants to adhere to. Please read the [full text](https://code.facebook.com/pages/876921332402685/open-source-code-of-conduct) so that you can understand what actions will and will not be tolerated.
134 changes: 30 additions & 104 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,115 +1,41 @@
This provides guidance on how to contribute various content to `hacklang.org`.
# Contributing to hacklang.org

## Getting started
We want to make contributing to this project as easy and transparent as
possible.

You should only have to do these one time.
## Our Development Process

- Rename this file to `CONTRIBUTING.md`.
- Rename `EXAMPLE-README-FOR-RUNNING-DOCS.md` to `README.md` (replacing the existing `README.md` that came with the template).
- Rename `EXAMPLE-LICENSE` to `LICENSE`.
- Checkout the [template information](./TEMPLATE-INFORMATION.md).
- Review `./_config.yml`.
- Make sure you update `title`, `description`, `tagline` and `gacode` (Google Analytics) in `./_config.yml`.
All development is directly through GitHub. Most contributions will be made via
pull requests.

## Basic Structure
## Pull Requests
We actively welcome your pull requests.

Most content is written in markdown. You name the file `something.md`, then have a header that looks like this:
1. Fork the repo and create your branch from `master`.
2. If you've added code that should be tested, add tests.
3. If you've changed APIs, update the documentation.
4. Ensure the test suite passes.
5. Make sure your code lints.
6. If you haven't already, complete the Contributor License Agreement ("CLA").

```
---
docid: getting-started
title: Getting started with ProjectName
layout: docs
permalink: /docs/getting-started.html
---
```
## Contributor License Agreement ("CLA")
In order to accept your pull request, we need you to submit a CLA. You only need
to do this once to work on any of Facebook's open source projects.

Customize these values for each document, blog post, etc.
Complete your CLA here: <https://code.facebook.com/cla>

> The filename of the `.md` file doesn't actually matter; what is important is the `docid` being unique and the `permalink` correct and unique too).
## Issues
We use GitHub issues to track public bugs. Please ensure your description is
clear and has sufficient instructions to be able to reproduce the issue.

## Landing page
Facebook has a [bounty program](https://www.facebook.com/whitehat/) for the safe
disclosure of security bugs. In those cases, please go through the process
outlined on that page and do not file a public issue.

Modify `index.md` with your new or updated content.
## Coding Style
* 2 spaces for indentation rather than tabs
* 80 character line length

If you want a `GridBlock` as part of your content, you can do so directly with HTML:

```
<div class="gridBlock">
<div class="blockElement twoByGridBlock alignLeft">
<div class="blockContent">
<h3>Your Features</h3>
<ul>
<li>The <a href="http://example.org/">Example</a></li>
<li><a href="http://example.com">Another Example</a></li>
</ul>
</div>
</div>
<div class="blockElement twoByGridBlock alignLeft">
<div class="blockContent">
<h3>More information</h3>
<p>
Stuff here
</p>
</div>
</div>
</div>
```

or with a combination of changing `./_data/features.yml` and adding some Liquid to `index.md`, such as:

```
{% include content/gridblocks.html data_source=site.data.features imagealign="bottom"%}
```

## Blog

To modify a blog post, edit the appopriate markdown file in `./_posts/`.

Adding a new blog post is a four-step process.

> Some posts have a `permalink` and `comments` in the blog post YAML header. You will not need these for new blog posts. These are an artifact of migrating the blog from Wordpress to gh-pages.
1. Create your blog post in `./_posts/` in markdown (file extension `.md` or `.markdown`). See current posts in that folder or `./doc-type-examples/2016-04-07-blog-post-example.md` for an example of the YAML format. **If the `./_posts` directory does not exist, create it**.
- You can add a `<!--truncate-->` tag in the middle of your post such that you show only the excerpt above that tag in the main `/blog` index on your page.
1. If you have not authored a blog post before, modify the `./_data/authors.yml` file with the `author` id you used in your blog post, along with your full name and Facebook ID to get your profile picture.
1. [Run the site locally](./README.md) to test your changes. It will be at `http://127.0.0.1/blog/your-new-blog-post-title.html`
1. Push your changes to GitHub.

## Docs

To modify docs, edit the appropriate markdown file in `./_docs/`.

To add docs to the site....

1. Add your markdown file to the `./_docs/` folder. See `./doc-type-examples/docs-hello-world.md` for an example of the YAML header format. **If the `./_docs/` directory does not exist, create it**.
- You can use folders in the `./_docs/` directory to organize your content if you want.
1. Update `_data/nav_docs.yml` to add your new document to the navigation bar. Use the `docid` you put in your doc markdown in as the `id` in the `_data/nav_docs.yml` file.
1. [Run the site locally](./README.md) to test your changes. It will be at `http://127.0.0.1/docs/your-new-doc-permalink.html`
1. Push your changes to GitHub.

## Header Bar

To modify the header bar, change `./_data/nav.yml`.

## Top Level Page

To modify a top-level page, edit the appropriate markdown file in `./top-level/`

If you want a top-level page (e.g., http://your-site.com/top-level.html) -- not in `/blog/` or `/docs/`....

1. Create a markdown file in the root `./top-level/`. See `./doc-type-examples/top-level-example.md` for more information.
1. If you want a visible link to that file, update `_data/nav.yml` to add a link to your new top-level document in the header bar.

> This is not necessary if you just want to have a page that is linked to from another page, but not exposed as direct link to the user.
1. [Run the site locally](./README.md) to test your changes. It will be at `http://127.0.0.1/your-top-level-page-permalink.html`
1. Push your changes to GitHub.

## Other Changes

- CSS: `./css/main.css` or `./_sass/*.scss`.
- Images: `./static/images/[docs | posts]/....`
- Main Blog post HTML: `./_includes/post.html`
- Main Docs HTML: `./_includes/doc.html`
## License
By contributing to hacklang.org, you agree that your contributions will be licensed
under the LICENSE file in the root directory of this source tree.
81 changes: 10 additions & 71 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,80 +1,19 @@
## The hacklang.org landing page content
# The hacklang.org landing page content

This directory will contain the landing page and other documentation for [hacklang.org](http://hacklang.org). It will contain links to the [Hack user documentation over at docs.hhvm.com](http://docs.hhvm.com/hack) and other relevant places. [hacklang.org](http://hacklang.org) will be hosted on GitHub pages.

### Contributing
## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md) for details on how to add or modify content.

### Run the Site Locally
## Run the Site Locally

The requirements for running a GitHub pages site locally is described in [GitHub help](https://help.github.com/articles/setting-up-your-github-pages-site-locally-with-jekyll/#requirements). The steps below summarize these steps.
[hacklang.org](http://hacklang.org) uses [Docusaurus](https://docusaurus.io).

> If you have run the site before, you can start with step 1 and then move on to step 5.
1. Fork and clone that repo.
1. `cd website`
1. `yarn install`
1. `yarn start`

1. Ensure that you are in the root directory of the hacklang.org repo (i.e., the same directory where this `README.md` exists). The below RubyGems commands, etc. must be run from there.

1. Make sure you have Ruby and [RubyGems](https://rubygems.org/) installed.

> Ruby >= 2.2 is required for the gems. On the latest versions of Mac OS X, Ruby 2.0 is the
> default. Use `brew install ruby` (or your preferred upgrade mechanism) to install a newer
> version of Ruby for your Mac OS X system.
1. Make sure you have [Bundler](http://bundler.io/) installed.

```
# may require sudo
gem install bundler
```
1. Install the project's dependencies

```
# run this in the 'docs' directory
bundle install
```

> If you get an error when installing `nokogiri`, you may be running into the problem described
> in [this nokogiri issue](https://github.com/sparklemotion/nokogiri/issues/1483). You can
> either `brew uninstall xz` (and then `brew install xz` after the bundle is installed) or
> `xcode-select --install` (although this may not work if you have already installed command
> line tools).
1. Run Jekyll's server.

- On first runs or for structural changes to the documentation (e.g., new sidebar menu item), do a full build.

```
bundle exec jekyll serve
```

- For content changes only, you can use `--incremental` for faster builds.

```
bundle exec jekyll serve --incremental
```

> We use `bundle exec` instead of running straight `jekyll` because `bundle exec` will always use the version of Jekyll from our `Gemfile`. Just running `jekyll` will use the system version and may not necessarily be compatible.
- To run using an actual IP address, you can use `--host=0.0.0.0`

```
bundle exec jekyll serve --host=0.0.0.0
```

This will allow you to use the IP address associated with your machine in the URL. That way you could share it with other people.

e.g., on a Mac, you can your IP address with something like `ifconfig | grep "inet " | grep -v 127.0.0.1`.

1. Either of commands in the previous step will serve up the site on your local device at http://127.0.0.1:4000/ or http://localhost:4000.

### Updating the Bundle

The site depends on Github Pages and the installed bundle is based on the `github-pages` gem.
Occasionally that gem might get updated with new or changed functionality. If that is the case,
you can run:

```
bundle update
```

to get the latest packages for the installation.
## License
hacklang.org is CC BY-NC 4.0 licensed, as found in the LICENSE file.

0 comments on commit 2c59657

Please sign in to comment.