start

Getting Started

View Community Pages
You can use these steps to create a website with free GitHub hosting

The following can be used to host a custom page within the "apps" repo

1. First, fork the localsite repo, the apps repo, and the io repo. Turn on GitHub Pages for each repo.
   After a few minutes, you can view your fork at [your account].github.io/apps
2. Activate a webroot on your local computer for http://localhost:8887
3. Then clone the three forked repos into the same local webroot folder.
4. Copy the base page folder locally, change parameters and deploy your updates.
5. Fetch upstream changes to your forked repos.
6. Point a domain at your repos (optional)

Here are details for the steps above...

Local Webroot Setup

1. Fork repos and turn on Github Pages

Clone forks of the parent repos so you can review your changes online before submitting a pull request (PR).
Click the "Fork" button in the upper right of each of the following pages:

localsite repo io repo apps repo

Activate GitHub Pages for each of your forked repos by going to "Settings > Pages" and choosing "main" (or master) then save.

IMPORTANT: DO NOT SELECT A THEME - The Jekyll theme will break the modular site integration.

Wait a few minutes for a new GitHub Pages site to become available at a link in the following format:

https://[your account].Github.io/[repo name]

2. Activate a webroot folder on your computer

The following will allow you to launch http://localhost:8887/localsite/.  You'll view multiple repos in the same webroot.

Create a web root folder called "webroot" or "modelearth", or use your existing web root.
Go to the web root folder and run the following to view pages locally at http://localhost:8887

python -m http.server 8887

You can run the command above to start localhost whenever you restart your computer. If that dose't work, here are more options for activating your webroot.

3. Clone forked repos into your webroot

Now go to your github account and clone the forked repos listed above.

To clone, click the green "Code" button followed by "Open in GitHub Desktop."

Save the clone in the webroot folder you created in step 1.

A static page should now be visible at http://localhost:8887/localsite/

Also clone the io repo into the same webroot to include the input-output widgets. Learn more

Also clone the apps repo if you are making a custom page.

To redirect into a repo, you can place an index.html file in your webroot with the following:

<script language="JavaScript">window.location="localsite/"</script>

4. Deploy your updates

Deploy your updates using GitHub. If you are not a project collaborator, GitHub Desktop will prompt you to create a project fork on GitHub. Place a pull request when your updates are ready for review.

Mac Users: To avoid commiting your local .DS_Store files to GitHub, you can run the following to ignore .DS_Store files during commits forever. The .DS_Store files will continue to set icon sizes in your local file manager.

git config --global core.excludesfile ~/.gitignore  
echo .DS_Store >> ~/.gitignore

If you encounter the error "xcrun: error: invalid active developer path", install the Xcode toolkit first.

You can view hidden files by toggling Command+Shift+Dot. Note that .DS_Store will not be displayed.
To fix a conflict you may need delete the .DS_Store within the Github.com website.

5. Fetch upstream changes to your forked repos

Occasionally merge in updates from parent repos by clicking "Fetch Upstream > Fetch and Merge" in GitHub.

6. Point a domain at your repos (optional)

You can point a domain at all the repos in your Github account with the steps below.

• Use CloudFlare.com as a free proxy for your domain name - setup steps - more about Cloudflare with GitHub. AWS can also be used.

• Important: If you are using the same domain for Google email accounts, avoid adding the 4 Google A records (these prevent adding the CNAME record). You'll only need to add the 5 MX records provided by Google.

• Create a repo in your primary account matching the name of the account: [github username].github.io

• Click settings and activate GitHub Pages for your [github username].github.io and each repo that will be an additional subfolder in your site. (This requires also doing the Special Trick below.)

• Add your custom domain name to the root repo called [github username].github.io.

• Special Trick: When you add a CNAME record for your domain in CloudFlare use @ to indicate the root, and point a different secondary account in Github as [secondary github username].github.io. By using a secondary GitHub username, more than one adjacent repo folder will be accessible through your primary domain. (The "localsite" repo can then be forked and shared locally with your primary site.)

• Wait 2 to 10 minutes for new GitHub Pages site to become available.

• Activate GitHub Pages for each additional repo residing within the primary account. These can be forks from other accounts.

• Avoid putting referenced files in your [github username].github.io root repo because it won't be the root of your site when you view on localhost.

• Fork the "localsite" repo into your GitHub account if you'd like to include it's functionality in any of your sites. Turn on GitHub pages to display at YourDomain.com/localsite/

Additional Resources

The Localsite Framework is designed to allow multiple Github repos to communicate using hash values.

View Starter Samples - maps, charts, widgets. Join us on Slack for pointers.

Learn more about JAM Stack Development - the process of creating fast sites using static pages with CSV files, JSON and APIs.

Edit online using stackedit.io and Dillinger Markdown to HTML

AWS Amplify, and site hosting info - Azure, Firebase, GitHub Pages, Netlify and more.

---

Edit the page above in Github - Edit in StackEdit - Click folder icon in upper right within StackEdit. (Direct links are not yet available in StackEdit)