|
| 1 | +# Contributing to fortran-lang.github.io |
| 2 | + |
| 3 | +Fortran-lang.github.io is open-source and contributions are welcome! |
| 4 | +The Fortran-lang site uses the Ruby-based [Jekyll static site generator](https://jekyllrb.com/). |
| 5 | +To contribute you will therefore need to install Jekyll on your development computer. |
| 6 | +See [README.md](README.md) for how to setup Jekyll and build the site. |
| 7 | + |
| 8 | +* See [PACKAGES](./PACKAGES.md) for how to add an entry to the [Package index](https://fortran-lang.org/packages) |
| 9 | + |
| 10 | +* See [MINIBOOKS](./MINIBOOKS.md) for how to write and structure a mini-book tutorial for the [Learn](https://fortran-lang.org/learn) section |
| 11 | + |
| 12 | +## Workflow |
| 13 | + |
| 14 | +Contributions to the site are made by pull request to the github repository: <https://github.com/fortran-lang/fortran-lang.github.io/>. |
| 15 | + |
| 16 | +The workflow for doing so takes the following form: |
| 17 | + |
| 18 | +1. Create/update a personal fork of fortran-lang.github.io |
| 19 | + - (See [github help: syncing a fork](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/syncing-a-fork) ) |
| 20 | + |
| 21 | +2. Create a new branch in your fork |
| 22 | + - The branch name should concisely describe your contribution, _e.g._ `fix-spelling-homepage`, `update-compiler-info` |
| 23 | + |
| 24 | +3. Perform your changes on the local branch |
| 25 | + |
| 26 | +4. Push your modified branch to your local fork |
| 27 | + - _e.g._ `git push --set-upstream origin fix-spelling-homepage` |
| 28 | + |
| 29 | +5. Create a pull request in the fortran-lang/fortran-lang.github.io from your modified fork branch |
| 30 | + - (See [github help: creating a pull request](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request) ) |
| 31 | + |
| 32 | +__Note: Before opening a pull request you must build your changes locally using Jekyll (see [README.md](README.md)) to verify that your changes build correctly and render as you expect.__ |
| 33 | + |
| 34 | +Your pull request will be reviewed by other members of the community who may request changes. |
| 35 | + |
| 36 | +__Note: You can continue to push changes to your fork branch after you open a pull request - the pull request will update accordingly__ |
| 37 | + |
| 38 | +Once your pull request is approved, usually by at least two other community members, it will be merged into the fortran-lang.github.io master branch by the maintainers at which point it will be published to the fortran-lang.org site. |
| 39 | + |
| 40 | +If required, the repository maintainers can build a public preview of your proposed changes which will be available to view at `fortran-lang.org/pr/<pr_id>/` where `<pr_id>` is the numeric identifier of your pull request. |
| 41 | + |
| 42 | +This allows reviewers to directly view the generated result of your PR. |
| 43 | +After a pull request has been merged and successfully rendered, the maintainers will delete the preview build. |
| 44 | + |
| 45 | + |
| 46 | +## Style guide |
| 47 | + |
| 48 | +### External links |
| 49 | + |
| 50 | +It is recommended practice for off-site hyperlinks to open in a new tab. |
| 51 | +On `Fortran-lang.org` all such links will automatically be suffixed with a new-tab icon; |
| 52 | +this gives site users prior expectation that the link will lead them off-site while |
| 53 | +keeping fortran-lang.org open in a previous tab. |
| 54 | + |
| 55 | +__Example:__ Open link in new tab (HTML or markdown) |
| 56 | +```html |
| 57 | +<a href="https://fortran-lang.discourse.group/" target="_blank" rel="noopener">Discourse</a> |
| 58 | +``` |
| 59 | + |
| 60 | +### Internal site links |
| 61 | + |
| 62 | +Hyperlinks that point to other parts of the fortran-lang.org website should be prefixed with `{{ site.baseurl }}` - this is important for generating pull request previews (see [here](https://byparker.com/blog/2014/clearing-up-confusion-around-baseurl/) for an explanation). |
| 63 | + |
| 64 | +__Example:__ markdown link |
| 65 | + |
| 66 | +``` |
| 67 | +[Fortran-lang news]({{site.baseurl}}/News) |
| 68 | +``` |
| 69 | + |
| 70 | +__Example:__ html link |
| 71 | + |
| 72 | +``` |
| 73 | +<a href="{{site.baseurl}}/Packages">Fortran packages</a> |
| 74 | +``` |
| 75 | + |
| 76 | +### Icon packs |
| 77 | + |
| 78 | +Icons are an easy way to improve page aesthetic by breaking-up otherwise monotonic text passages |
| 79 | +and drawing attention to headings or key information. |
| 80 | + |
| 81 | +Three icon packs are available for use on `fortran-lang.org`: |
| 82 | + |
| 83 | +* [Font awesome](https://fontawesome.com/icons?d=gallery) (CC BY 4.0 License) |
| 84 | + |
| 85 | +* [Feather](https://feathericons.com/) (MIT) |
| 86 | + |
| 87 | +* [Devicon](https://konpa.github.io/devicon/) (MIT) |
| 88 | + |
| 89 | + |
| 90 | +__Example:__ Font awesome |
| 91 | +```html |
| 92 | +<i class="fas fa-info-circle"></i> |
| 93 | +``` |
| 94 | + |
| 95 | +__Example:__ Feather |
| 96 | + |
| 97 | +```html |
| 98 | +<i data-feather="globe"></i> |
| 99 | +``` |
| 100 | + |
| 101 | +__Example:__ Devicon |
| 102 | + |
| 103 | +```html |
| 104 | +<i class="devicon-github-plain"></i> |
| 105 | +``` |
| 106 | + |
| 107 | +Visit the respective websites to browse available icons. |
| 108 | + |
| 109 | +__Note:__ font-awesome icons currently appear to vertically-align with text better - |
| 110 | +we need to get feather icons to do the same. |
| 111 | + |
| 112 | + |
| 113 | +### Page contents |
| 114 | + |
| 115 | +It is sometimes useful to display a hyperlinked page contents for lengthy pages. |
| 116 | +There are two ways to do this on `fortran-lang.org`. |
| 117 | + |
| 118 | +__Option 1: Use the `book` layout__ |
| 119 | + |
| 120 | +The `book` layout is the layout used for mini-book tutorials; |
| 121 | +it includes a non-scrolling sidebar which is automatically populated |
| 122 | +by the `<h2>` headings on the current page. |
| 123 | + |
| 124 | +__Option 2:__ |
| 125 | + |
| 126 | +If you just want a list of headings at the top of your page, |
| 127 | +include the following snippet, which will be automatically |
| 128 | +populated by the `<h2>` headings on the current page. |
| 129 | + |
| 130 | +```html |
| 131 | +<ul id="page-nav"></ul> |
| 132 | +``` |
| 133 | + |
| 134 | +__Implementation:__ |
| 135 | +the functionality described above is implemented in the javascript file |
| 136 | +[assets/js/page_nav.js](./assets/js/page_nav.js). |
0 commit comments