-
Notifications
You must be signed in to change notification settings - Fork 8
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
171b84e
commit ea3d7a1
Showing
2 changed files
with
44 additions
and
22 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,37 +1,59 @@ | ||
# RoamJS Static Site | ||
|
||
For more about the RoamJS Static Site Service, visit [https://roamjs.com/services/static-site](https://roamjs.com/services/static-site). | ||
Deploying your Roam graph as a public website! | ||
|
||
# Github Action | ||
## Introduction | ||
Roam is a powerful CMS (content management system), not just for personal knowledge management but for public information as well. There are a couple of problems though with using Roam itself as the public-facing display of that information: | ||
- Initial load time is slow | ||
- It is not SEO-friendly | ||
- The user interface is foreign to most visitors of your graph | ||
This RoamJS Extension allows you to use your Roam graph as the CMS of your own public website. Launching a RoamJS Static Site will download the content of your Roam graph and upload it as web pages to a managed website for you based on your configuration and filters. | ||
|
||
A GitHub action for generating a static site from your Roam Graph is also available. You could use this for free to upload the generated files to your own hosting service. It uses the same underlying logic as the Static Site extension itself, querying the data by running a headless browser and logging into your account. | ||
## Getting Started | ||
Hosting websites for the user is a premium feature of this extension. It will cost $12 per website per month to deploy your website to RoamJS. While we only currently support maximum 1 website per user, this allows us to support multiple websites per user in the future and allows users to subscribe for free to help with other users' websites. You can subscribe directly within Roam by heading to the `roam/js/static-site` page. Upon installing this extension, you should be redirected there automatically. | ||
|
||
## Inputs | ||
### Domain | ||
Enter the domain that you would like your website to be reachable at. **You must already own the domain from another registrar.** If instead of a custom domain, you would like to use a RoamJS subdomain, hit the toggle at the top to switch from custom domain to RoamJS subdomain. You may transfer the website to your own custom domain later at any time. | ||
|
||
### `roam_username` | ||
### Index | ||
The index field specifies which page in your graph will map to your home page. If you choose a page that doesn't already exist, it will be created for you with some block text so that it doesn't get cleaned up by Roam. Your index page will be included in your website no matter how you specify your filters. | ||
|
||
**Required** Your Roam username | ||
### Filters | ||
Filters determine which subset of your graph will be included as pages in your public website. By default, only your index page will be deployed. However, the extension supports four types of filters to help specify which other pages in your graph are included: | ||
- `TAGGED WITH` - All pages that reference a given tag will be included. The default value uses the `#Website` tag | ||
- `STARTS WITH` - All pages that have a given prefix will be included. Useful for pages with namespaces. | ||
- `DAILY` - Include all of the daily note pages in your graph, each with its own webpage. | ||
- `ALL` - Includes all of the pages in your graph, each with its own webpage | ||
|
||
### `roam_password` | ||
### Launch | ||
Once you have configured the required fields above, you will be able to launch your RoamJS website! | ||
|
||
**Required** Your Roam password | ||
The dashboard will display the progress of the launch as the backend resources are being set up. At some point, it will require validation on the user's end in order to continue. It will display these directions in blue text depending on the domain you opted to take. These directions will also be emailed to you in case you navigated away from Roam. | ||
- If you chose a standard custom domain, the dashboard will display four name servers. Go to the domain settings of your domain in the registrar you bought the domain, and click edit name servers. Replace whatever values are present with the four name servers that RoamJS has allocated for your website. | ||
- If you chose a subdomain of a custom domain you own, the dashboard will display a CNAME record's name and value. Go to the domain settings of your domain in the registrar you bought the domain, and click add a record. The record you add should be of type `CNAME` and should have the name + value displayed on the dashboard. | ||
- If you chose a RoamJS subdomain, you will not need to do any additional validation. | ||
|
||
### `roam_graph` | ||
The validation step should take 5-10 minutes to propagate those changes globally and validate that you are the proper owner of the domain. Once you see the blue text disappear and the "CREATING NETWORK" step appear, then you'll know that validation was successful. | ||
|
||
**Required** Your Roam Graph | ||
When the launch process finishes, the progress bar will disappear and a green `Live` text will appear on the dashboard. If you chose a subdomain of a custom domain you own, you will need to add one more CNAME record to your domain settings, the details of which will have been sent to you over email. Otherwise, your site will already be ready to go. | ||
|
||
### `config_path` | ||
Click the green Live link on your dashboard to view your new RoamJS-powered website! | ||
|
||
**Required** The path to the json file use to override and Roam config settings, relative to `GITHUB_WORKSPACE`. Default value is `static_site.json`. | ||
### Demo | ||
|
||
## Usage | ||
<video src="https://roamjs.com/loom/f5df02f4d49445c0891e2efd756e667c.mp4" controls="controls"></video> | ||
|
||
```yaml | ||
uses: dvargas92495/roamjs-static-site@2022-01-22-00-07 | ||
with: | ||
roam_username: [email protected] | ||
roam_password: ${{ secrets.ROAM_PASSWORD }} | ||
roam_graph: dvargas92495 | ||
``` | ||
[View on Loom](https://www.loom.com/share/f5df02f4d49445c0891e2efd756e667c) | ||
|
||
I have an [example repository](https://github.com/dvargas92495/public-garden) showcasing this action. The resulting site is reachable at https://garden.davidvargas.me. | ||
## Table of Contents | ||
There are all sorts of ways you could customize your website. Dive into any of the pages below to explore! | ||
|
||
1. [Core Features](https://roamjs.com/extensions/static-site/core_features) | ||
2. [Templates](https://roamjs.com/extensions/static-site/templates) | ||
3. [Filters](https://roamjs.com/extensions/static-site/filters) | ||
4. [Theme](https://roamjs.com/extensions/static-site/theme) | ||
5. [Plugins](https://roamjs.com/extensions/static-site/plugins) | ||
6. [Components](https://roamjs.com/extensions/static-site/components) | ||
7. [Advanced Features](https://roamjs.com/extensions/static-site/advanced_features) | ||
8. [Showcase](https://roamjs.com/extensions/static-site/showcase) | ||
8. [Developer Docs](https://roamjs.com/extensions/static-site/developer_docs) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters