Skip to content
Permalink
Browse files
Update asf-pelican-gettingstarted.md
updating the config info to refer to .asf.yaml and .pelicanconf.yaml
  • Loading branch information
cottage14 committed Apr 15, 2022
1 parent 74a1d8b commit c708f20a130f3fdad61091afdec0bbc8938c461c
Showing 1 changed file with 51 additions and 19 deletions.
@@ -7,15 +7,15 @@ Review the [Apache Template example](https://template.staged.apache.org/) to see

## How to use this template

1. Review the <a href="https://github.com/apache/template-site" target="_blank">code repository for ASF-Pelican</a> to confirm that it may provide the features your project site needs.
1. Review the <a href="https://github.com/apache/template-site" target="_blank">code repository for ASF-Pelican</a> to confirm that it provides the features your project site needs.

2. Create a <a href="https://issues.apache.org/jira/Jira" target="_blank">Jira ticket</a>, requesting Infra to create a repository using this template for your project. Provide a name and short description for the repository. Infra will confirm the repository's location when it is ready for you.

3. **Note**: we strongly suggest that you do your site development in a branch rather than the trunk of the repository, and then merge the branch into the trunk when you are sure that everything as working as you would like it. Each commit to the trunk triggers an automatic build to update your live site; this is great for trivial changes like correcting typos, but more of a challenge if you are making major changes and it turns out that there is an error in your code that disables your live site.
**Note**: we strongly suggest that you do your site development in a branch rather than the trunk of the repository, and then merge the branch into the trunk when you are sure that everything as working as you would like it. Each commit to the trunk triggers an automatic build to update your live site; this is great for trivial changes like correcting typos, but more of a challenge if you are making major changes and it turns out that there is an error in your code that disables your live site.

<!--- Review [ASF Pelican feature branches](asf-pelican-branches.html). --->

4. In `theme/apache/templates`, update the theme's `base.html` to fit your site's requirements.
3. In `theme/apache/templates`, update the theme's `base.html` to fit your site's requirements.

The example has the following frameworks.

@@ -27,26 +27,44 @@ Review the [Apache Template example](https://template.staged.apache.org/) to see
- [Bootstrap 4.3.1](https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/css/bootstrap.css)
- [GitHub Markdown 3.0.1](https://cdnjs.cloudflare.com/ajax/libs/github-markdown-css/3.0.1/github-markdown.css)

For fenced code highlighting, have a look at [highlightjs](https://highlightjs.org).
For fenced code highlighting, review <a href="https://highlightjs.org" target="_blank")>highlightjs</a>.

- The `content/images` folder holds example logo files. Place your other site image files here.
- The `content/images` folder holds example logo files. Place your own site's image files here.

5. Determine if your site requires a [data model](https://infra.apache.org/asf-pelican-data.html).
4. Determine if your site requires a [data model](https://infra.apache.org/asf-pelican-data.html).

- The `.ezmd` files in the [content](content) directory show examples
- [`asfdata.yaml`](asfdata.yaml) has manuy examples
- The `.ezmd` files in the <a href="https://github.com/apache/template-site/tree/main/content" target="_blank">content</a> directory show examples
- <a href="https://github.com/apache/template-site/blob/main/asfdata.yaml" target="_blank">asfdata.yaml</a> has many examples
- Remove the following if you do not need a data model:
1. `asfdata.py` and `asfreader.py` [Plugins](/theme/plugins)
2. `asfdata.yaml`
3. `data` directory

6. Edit your [configuration](pelicanconf.py)

- Website specific
- `PLUGINS`
- `ASF_DATA` - `asfdata.py` plugin settings
- `ASF_GENID` - `asfgenid.py` plugin settings
`asfgenid.py` performs a series of html fixups including permalinks, heading ids, and table of contents
1. `asfdata.yaml`
2. `data/eccn` directory

5. Edit the `asf.yaml` configuration file:

```
pelican:
notify: wave@apache.org
autobuild: preview/*
target: YOUR SITE'S REPOSITORY
theme: theme/apache
whoami: main
staging:
profile: ~
whoami: YOUR SITE'S REPOSITORY
autostage: preview/*
```

6. Update `pelicanconfig.yaml` with your site's information:

```
site:
name: YOUR SITE'S NAME
description: DESCRIPTION OF YOUR SITE
domain: YOUR SITE'S DOMAIN (like projectname.apache.org)
logo: images/logo.png
repository: YOUR SITE'S CODE REPOSITORY
```

7. Create your [content](content)

@@ -65,3 +83,17 @@ Review the [Apache Template example](https://template.staged.apache.org/) to see
Please let us know if you run into issues with the template.

- [Issues](https://github.com/apache/template-site/issues)

## Earlier versions

Earlier versions of this template made use of a `pelicanconf.py` configuration file. The current version uses `.asf.yaml` and `pelicanconf.yaml`, as noted above. We retain the earlier instruction for the projects using the earlier version of the template; however, any project starting with the template now should use the files and instructions noted above.

```
Edit the `pelicanconf.py` configuration file:
- Website specific
- `PLUGINS`
- `ASF_DATA` - `asfdata.py` plugin settings
- `ASF_GENID` - `asfgenid.py` plugin settings
`asfgenid.py` performs a series of html fixups including permalinks, heading ids, and table of contents
```

0 comments on commit c708f20

Please sign in to comment.