Skip to content

Commit

Permalink
Add README
Browse files Browse the repository at this point in the history
  • Loading branch information
quincylvania committed Jan 19, 2024
1 parent 6bd0b4f commit b78df14
Show file tree
Hide file tree
Showing 5 changed files with 92 additions and 10 deletions.
85 changes: 85 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
---
layout: page
permalink: /
---
<img src="img/logo.svg" style="border:none;width:100px;"/>

# Dogwood

Dogwood is the [theme](https://jekyllrb.com/docs/themes/) for the [Jekyll](https://jekyllrb.com) static site generator powering [openstreetmap.us](https://openstreetmap.us). While the content for the OpenStreetMap US website is kept internal to the organization, we've decided to open source the site's theme for the benefit of the community.

Dogwood pushes the envelope of what's possible with static site generators. It supports complex sites with thousands of interconnected, customizable pages, each with their own requirements. For example, you can make a page for a person that links to and from posts they've written, event they've spoken at, and projects they're a part of.

Dogwood is under active development and is not currently versioned. Breaking changes may occur without notice, so we recommend targeting a specific commit of the project of simply forking it.

The Dogwood theme is named for Virginia's state flower, since the OpenStreetMap US [website redesign](https://openstreetmap.us/news/2023/06/website-redesign/) was announced onstage at [State of the Map US 2023](https://openstreetmap.us/state-of-the-map-us/2023) in Richmond, Virginia.

## Installation

Dogwood is not distributed as a Ruby gem at this time. However, can still use Dogwood as a theme for your Jekyll site.

Open your terminal and `cd` into the repo's directory. Add Dogwood as a submodule:

```
$ git submodule add https://github.com/osmus/dogwood.git
```

This will clone the theme repo into a `dogwood` folder and also add a .gitmodules file:

```
[submodule "dogwood"]
path = dogwood
url = https://github.com/osmus/dogwood.git
```

Next, add these lines to your Jekyll site's `Gemfile`:

```ruby
# theme
gem "osmus-dogwood", path: "dogwood"

# theme plugins
gem "absolute-urls", path: "./dogwood/_plugins/absolute-urls"
gem "post-aliases", path: "./dogwood/_plugins/post-aliases"
gem "unwrap-img", path: "./dogwood/_plugins/unwrap-img"
```

Add this line to your Jekyll site's `_config.yml`:

```yaml
theme: osmus-dogwood
```
And then execute:
```
$ bundle install
```

If you're already running your dev server you'll need to manually restart it for the config changes to take effect

## Get involved

### Code of Conduct
Participation is subject to the [OpenStreetMap US Code of Conduct](https://wiki.openstreetmap.org/wiki/Foundation/Local_Chapters/United_States/Code_of_Conduct_Committee/OSM_US_Code_of_Conduct). Please take a moment to review the CoC prior to contributing, and remember to be nice :)

### Contributing

You can open an [issue](https://github.com/osmus/dogwood/issues) in this repository if you have a question, comment, or idea. Please search existing issues first in case someone else had the same thought. [Pull request](https://github.com/osmus/dogwood/pulls) are public, but we recommend opening or commenting on an issue before writing any code so that we can make sure your work is aligned with the goals of the project.

### Development setup
1. [Clone the repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository)
2. Open your terminal and `cd` into the repo's directory
3. Run `bundle install` to install the Ruby gems
4. Run `bundle exec jekyll serve` (or simply `jekyll serve`) to start the development server
5. Visit [http://localhost:4000](http://localhost:4000) in your browser

## License

The theme is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

## Acknowledgements

* Dogwood was originally designed and developed by [Quincy Morgan](https://github.com/quincylvania) under contract to OpenStreetMap US
* Most icons by [FontAwesome](https://fontawesome.com)
* Thank you to the Jekyll team and to everyone who believes in open software and knowledge
5 changes: 2 additions & 3 deletions _config.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ logo: /img/logo.svg
logo_mono: /img/logo-mono.svg
future: true
timezone: America/New_York
github: osmus
github: osmus/dogwood
mastodon: https://en.osm.town/@OpenStreetMapUS
twitter: openstreetmapus
youtube_page: channel/UCQpS2iHNVR-_6nAxt87nwCw
Expand All @@ -19,8 +19,7 @@ links:
- link: /people/
- link: /blog/
- link: https://github.com/osmus/dogwood
label: Use Me!
class: no-cond
label: Use This Theme!
a_class: button bordered
plugins:
- jekyll-archives
Expand Down
4 changes: 3 additions & 1 deletion _includes/pagenav.html
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
{%- if page.title or pate.temp_title -%}
<div class="pagenav">
<div>
<a class="selflink" href="{{page.url | absolute_url}}">
Expand Down Expand Up @@ -42,4 +43,5 @@ <h1>{{page.temp_title | default: page.title}}</h1>
{% endfor %}
{% endif %}
</ul>
</div>
</div>
{%- endif -%}
4 changes: 2 additions & 2 deletions _sass/dogwood/_layout.scss
Original file line number Diff line number Diff line change
Expand Up @@ -115,7 +115,7 @@ code,
pre {
padding: 5px 4px;
font-family: Menlo, Bitstream Vera Sans Mono, Monaco, Consolas, monospace;
font-size: 0.675em;
font-size: 12px;
border-radius: 3px;
}
code {
Expand Down Expand Up @@ -1302,7 +1302,7 @@ article {
max-width: $text-width;
margin-bottom: $sp;
}
img, figure, .img-container {
img, figure, .img-container, div {
margin-bottom: $sp;
}
hr {
Expand Down
4 changes: 0 additions & 4 deletions index.html

This file was deleted.

0 comments on commit b78df14

Please sign in to comment.