You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Repository for generating online and PDF documentation for ISSM and storing publications based on ISSM.
2
3
3
-
This is a *bare-minimum* template to create a [Jekyll] site that:
4
+
The [generated documentation]is a [Jekyll] site that uses a customized version of the [Just the Docs] theme and is built and published on [GitHub Pages].
4
5
5
-
- uses the [Just the Docs] theme;
6
-
- can be built and published on [GitHub Pages];
7
-
- can be built and previewed locally, and published on other platforms.
6
+
## Making Changes to the Documentation
7
+
If you have write access to this repository, you can make and commit changes from a copy of the repository or make changes to pages directly through the GitHub interface. Alternatively, all users may fork this repository and submit pull requests with proposed changes.
8
8
9
-
More specifically, the created site:
10
-
11
-
- uses a gem-based approach, i.e. uses a `Gemfile` and loads the `just-the-docs` gem;
12
-
- uses the [GitHub Pages / Actions workflow] to build and publish the site on GitHub Pages.
13
-
14
-
To get started with creating a site, simply:
15
-
16
-
1. click "[use this template]" to create a GitHub repository
17
-
2. go to Settings > Pages > Build and deployment > Source, and select GitHub Actions
18
-
19
-
If you want to maintain your docs in the `docs` directory of an existing project repo, see [Hosting your docs from an existing project repo](#hosting-your-docs-from-an-existing-project-repo).
20
-
21
-
After completing the creation of your new site on GitHub, update it as needed:
22
-
23
-
## Replace the content of the template pages
24
-
25
-
Update the following files to your own content:
26
-
27
-
-`index.md` (your new home page)
28
-
-`README.md` (information for those who access your site repo on GitHub)
29
-
30
-
## Changing the version of the theme and/or Jekyll
31
-
32
-
Simply edit the relevant line(s) in the `Gemfile`.
33
-
34
-
## Adding a plugin
35
-
36
-
The Just the Docs theme automatically includes the [`jekyll-seo-tag`] plugin.
37
-
38
-
To add an extra plugin, you need to add it in the `Gemfile`*and* in `_config.yml`. For example, to add [`jekyll-default-layout`]:
39
-
40
-
- Add the following to your site's `Gemfile`:
41
-
42
-
```ruby
43
-
gem "jekyll-default-layout"
44
-
```
45
-
46
-
- And add the following to your site's `_config.yml`:
47
-
48
-
```yaml
49
-
plugins:
50
-
- jekyll-default-layout
51
-
```
52
-
53
-
Note: If you are using a Jekyll version less than 3.5.0, use the `gems` key instead of `plugins`.
54
-
55
-
## Publishing your site on GitHub Pages
56
-
57
-
1. If your created site is `YOUR-USERNAME/YOUR-SITE-NAME`, update `_config.yml` to:
2. Push your updated `_config.yml` to your site on GitHub.
71
-
72
-
3. In your newly created repo on GitHub:
73
-
- go to the `Settings` tab -> `Pages` -> `Build and deployment`, then select `Source`: `GitHub Actions`.
74
-
- if there were any failed Actions, go to the `Actions` tab and click on `Re-run jobs`.
75
-
76
-
## Building and previewing your site locally
9
+
It can take up to 10 minutes for changes to your site to publish after you push the changes to GitHub
77
10
11
+
### Previewing Changes Locally
78
12
Assuming [Jekyll] and [Bundler] are installed on your computer:
79
13
80
14
1. Change your working directory to the root directory of your site.
@@ -85,90 +19,8 @@ Assuming [Jekyll] and [Bundler] are installed on your computer:
85
19
86
20
The built site is stored in the directory `_site`.
87
21
88
-
## Publishing your built site on a different platform
89
-
90
-
Just upload all the files in the directory `_site`.
91
-
92
-
## Customization
93
-
94
-
You're free to customize sites that you create with this template, however you like!
95
-
96
-
[Browse our documentation][Just the Docs] to learn more about how to use this theme.
97
-
98
-
## Hosting your docs from an existing project repo
99
-
100
-
You might want to maintain your docs in an existing project repo. Instead of creating a new repo using the [just-the-docs template](https://github.com/just-the-docs/just-the-docs-template), you can copy the template files into your existing repo and configure the template's Github Actions workflow to build from a `docs` directory. You can clone the template to your local machine or download the `.zip` file to access the files.
101
-
102
-
### Copy the template files
103
-
104
-
1. Create a `.github/workflows` directory at your project root if your repo doesn't already have one. Copy the `pages.yml` file into this directory. GitHub Actions searches this directory for workflow files.
105
-
106
-
2. Create a `docs` directory at your project root and copy all remaining template files into this directory.
107
-
108
-
### Modify the GitHub Actions workflow
109
-
110
-
The GitHub Actions workflow that builds and deploys your site to Github Pages is defined by the `pages.yml` file. You'll need to edit this file to that so that your build and deploy steps look to your `docs` directory, rather than the project root.
111
-
112
-
1. Set the default `working-directory` param for the build job.
113
-
114
-
```yaml
115
-
build:
116
-
runs-on: ubuntu-latest
117
-
defaults:
118
-
run:
119
-
working-directory: docs
120
-
```
121
-
122
-
2. Set the `working-directory` param for the Setup Ruby step.
123
-
124
-
```yaml
125
-
- name: Setup Ruby
126
-
uses: ruby/setup-ruby@v1
127
-
with:
128
-
ruby-version: '3.3'
129
-
bundler-cache: true
130
-
cache-version: 0
131
-
working-directory: '${{ github.workspace }}/docs'
132
-
```
133
-
134
-
3. Set the path param for the Upload artifact step:
135
-
136
-
```yaml
137
-
- name: Upload artifact
138
-
uses: actions/upload-pages-artifact@v3
139
-
with:
140
-
path: docs/_site/
141
-
```
142
-
143
-
4. Modify the trigger so that only changes within the `docs` directory start the workflow. Otherwise, every change to your project (even those that don't affect the docs) would trigger a new site build and deploy.
144
-
145
-
```yaml
146
-
on:
147
-
push:
148
-
branches:
149
-
- "main"
150
-
paths:
151
-
- "docs/**"
152
-
```
153
-
154
-
## Licensing and Attribution
155
-
156
-
This repository is licensed under the [MIT License]. You are generally free to reuse or extend upon this code as you see fit; just include the original copy of the license (which is preserved when you "make a template"). While it's not necessary, we'd love to hear from you if you do use this template, and how we can improve it for future use!
157
-
158
-
The deployment GitHub Actions workflow is heavily based on GitHub's mixed-party [starter workflows]. A copy of their MIT License is available in [actions/starter-workflows].
159
-
160
-
----
161
-
162
-
[^1]: [It can take up to 10 minutes for changes to your site to publish after you push the changes to GitHub](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/creating-a-github-pages-site-with-jekyll#creating-your-site).
<!-- A PDF version of the following documentation is distributed with the ISSM source code and available for download <a href="https://github.com/ISSMteam/ISSM/blob/main/userguide.pdf" target="_blank" type="application/pdf">here</a>. -->
13
+
Welcome to the documentation page for the Ice-Sheet and Sea-level System Model (ISSM). Included here are instructions for installation and use of ISSM, development status and forecast, as well as information about how ISSM used and the team behind it.
14
14
15
-
<h2>Documentation Sections</h2>
15
+
Please feel free to let us know how this documentation could be improved. We also welcome contributions to the source code via fork and pull request.
0 commit comments