|
1 | | -typelevel website |
2 | | -================= |
| 1 | +# typelevel.org |
3 | 2 |
|
4 | | -This is the website of typelevel.scala. It is built on Jekyll and served at [typelevel.org](https://typelevel.org). |
| 3 | +This is the source of typelevel.org. It is built with [Laika] and deployed to GitHub Pages. |
5 | 4 |
|
6 | | -## Getting Started (the short version) |
| 5 | +## Get Started |
7 | 6 |
|
8 | | -If you just want to add a blog post or fix a typo in the content, here's how to get started. |
| 7 | +To work on the website, you will need: |
| 8 | +* Scala 3.5 or later |
| 9 | +* Java 21 or later |
9 | 10 |
|
10 | | -### Creating a blog post |
| 11 | +### Preview Server |
11 | 12 |
|
12 | | -1. Create a new file in the [`./collections/_posts`](./collections/_posts/) directory or copy an existing post. Its name should have the format `YYYY-MM-DD-short_title.md`. |
13 | | -2. Set the `title` (short title of the post, appears as the HTML `<title>`) and `author` (your GitHub user name) in the front matter. MathJax is available via `mathjax: true` inside the front matter. |
14 | | -3. If this is your first blog post, please indicate if you want your name and a profile picture to appear on the post. If not, you can remove the `author` field from the front matter. Add your details in `_data/authors.yml`. |
15 | | -4. Write your content using Markdown. For code highlighting, use the usual GitHub syntax: |
| 13 | +For the best experience, serve the website to immediately see your changes in a live preview. |
16 | 14 |
|
17 | | -```scala |
18 | | -def yourCode: Here |
| 15 | +```bash |
| 16 | +scala build.scala -- serve |
19 | 17 | ``` |
20 | 18 |
|
21 | | -If you haven't written a post before, please add yourself to `_data/authors.yml`. |
22 | | - |
23 | | -That's it, we'll take care of the rest. If you wish, you can also submit just a plain Markdown file and we'll be happy to integrate it. |
24 | | - |
25 | | -### Previewing your changes |
26 | | - |
27 | | -#### Bundler |
28 | | - |
29 | | -To preview your changes, you have to install [Bundler](https://bundler.io/) first. |
30 | | -To download and set up all necessary dependencies, run |
31 | | - |
32 | | -```console |
33 | | -$ bundle install |
34 | | -... lots of text ... |
35 | | -Bundle complete! 1 Gemfile dependency, 81 gems now installed. |
36 | | -Bundled gems are installed into `./vendor/bundle` |
| 19 | +Within a few seconds, a preview server will be available at http://localhost:8000/. Press `Ctrl+C` to stop the server. In case you need to use a different port, you may pass it as an option. |
| 20 | +```bash |
| 21 | +scala run build.scala -- serve --port 8080 |
37 | 22 | ``` |
38 | 23 |
|
39 | | -Then, you can generate the site by running |
40 | | - |
41 | | -```console |
42 | | -$ bundle exec jekyll serve -wl --baseurl '' |
43 | | -``` |
44 | | - |
45 | | -The generated site will end up in the `_site` directory. |
46 | | - |
47 | | -#### Nix |
| 24 | +### Write a blog post |
48 | 25 |
|
49 | | -A fully configured Jekyll is available as a Nix app. Assumes that you have [installed Nix](https://nixos.org/download.html) and [enabled flakes](https://nixos.wiki/wiki/Flakes#Installing_flakes). |
| 26 | +Blog posts (including event announcements) are added to the `src/blog/` directory. Content is written using [GitHub-flavored Markdown][gfm]. Code blocks support syntax highlighting in Scala and [several other languages][syntax]. Rendering of mathematical expressions is enabled for any document by setting `katex: true` in the configuration header and using the `@:math` directive. |
50 | 27 |
|
51 | | -```console |
52 | | -$ nix run github:typelevel/typelevel.github.com#jekyll build |
53 | | -warning: Git tree '/Users/ross.baker/src/typelevel.github.com' is dirty |
54 | | -Configuration file: /Users/ross.baker/src/typelevel.github.com/_config.yml |
55 | | - Source: /Users/ross.baker/src/typelevel.github.com |
56 | | - Destination: /Users/ross.baker/src/typelevel.github.com/_site |
57 | | - Incremental build: disabled. Enable with --incremental |
58 | | - Generating... |
59 | | - done in 3.635 seconds. |
60 | | - Auto-regeneration: disabled. Use --watch to enable. |
61 | 28 | ``` |
62 | | - |
63 | | -There is also a devshell for direct invocation, and a convenient alias: |
64 | | - |
65 | | -```console |
66 | | -$ nix develop github:typelevel/typelevel.github.com |
67 | | -🔨 Welcome to typelevel-org-shell |
68 | | - |
69 | | -[general commands] |
70 | | - |
71 | | - jekyll - a jekyll bundled with this site's dependencies |
72 | | - menu - prints this menu |
73 | | - tl-preview - preview the Jekyll site |
74 | | - |
75 | | -$ tl-preview |
76 | | -Configuration file: /home/you/src/typelevel.github.com/_config.yml |
77 | | - Source: /home/you/src/typelevel.github.com |
78 | | - Destination: /home/you/src/typelevel.github.com/_site |
79 | | - Incremental build: disabled. Enable with --incremental |
80 | | - Generating... |
81 | | - done in 3.336 seconds. |
82 | | - Auto-regeneration: enabled for '/home/you/src/typelevel.github.com' |
83 | | -LiveReload address: http://127.0.0.1:35729 |
84 | | - Server address: http://127.0.0.1:4000/ |
85 | | - Server running... press ctrl-c to stop. |
| 29 | +@:math |
| 30 | +\forall a,b,c \in S : (a \cdot b) \cdot c = a \cdot (b \cdot c) |
| 31 | +@:@ |
86 | 32 | ``` |
87 | 33 |
|
88 | | - |
89 | | - |
90 | | -## License |
91 | | - |
92 | | -Unless otherwise noted, all website content is licensed under a [Creative Commons Attribution 3.0 Unported License](https://creativecommons.org/licenses/by/3.0/deed.en_US). |
93 | | - |
94 | | -## Development |
95 | | - |
96 | | -### CSS |
97 | | - |
98 | | -The stylesheets are written in SASS, and can be found in the `css` and `_sass` directories. |
99 | | -It is being processed/compiled into regular CSS by Jekyll. |
100 | | - |
| 34 | +If this is your first blog post, be sure to add your author info to `src/directory.conf`. |
| 35 | + |
| 36 | +```hocon |
| 37 | +toolkitty { |
| 38 | + name: Toolkitty |
| 39 | + pronouns: "they/them" |
| 40 | + avatar: "https://github.com/toolkitty.png" |
| 41 | + github: toolkitty |
| 42 | + bluesky: toolkitty.bsky.social |
| 43 | + bio: "I am the mascot of the Scala Toolkit!" |
| 44 | +} |
101 | 45 | ``` |
102 | | -├── css/ |
103 | | -│ ├── main.scss # Custom CSS, brings all stylesheets together |
104 | | -├── _sass/ |
105 | | -│ ├── base/ |
106 | | -│ ├── components/ |
107 | | -│ ├── utils/ |
108 | | -``` |
109 | | - |
110 | | -### Javascript |
111 | | - |
112 | | -Javascript can be found in the `js/` folder, which also includes its dependencies. |
113 | | - |
114 | | -### Templates |
115 | | - |
116 | | -All templates/layouts can be found in the `_layouts` folder, except the blog layout, which is located inside its own subfolder `blog/`. |
117 | | - |
118 | | -### Images |
119 | | - |
120 | | -Images for styling purposes are located inside `img/`, photos inside `img/media/`. |
121 | | - |
122 | | -### Adding a project |
123 | | - |
124 | | -There are three types of projects: organization projects, affiliate projects, and core/featured projects. |
125 | 46 |
|
126 | | -To add an organization project, insert a new entry, alphabetically, in the `_data/projects.yml` file with the following keys: |
| 47 | +Note that event announcements use a custom template with additional fields specified in the configuration header. |
127 | 48 |
|
128 | | -```yml |
129 | | -- title: "Cats" |
130 | | - description: "A library intended to provide abstractions for functional programming in Scala, leveraging its unique features. Design goals are approachability, modularity, documentation and efficiency." |
131 | | - github: "https://github.com/typelevel/cats" |
132 | | - platforms: [js, jvm, native] |
133 | | - permalink: "https://typelevel.org/cats/" # optional |
| 49 | +``` |
| 50 | +{% |
| 51 | + laika.html.template: event.template.html |
| 52 | + date: "2025-08-15" # the date the post is published |
| 53 | + event-date: "August 22, 2025" # the actual date of the event |
| 54 | + event-location: "École Polytechnique Fédérale de Lausanne" |
| 55 | + tags: [events] |
| 56 | +%} |
134 | 57 | ``` |
135 | 58 |
|
136 | | -Right now nothing more than the correct front matter is required. |
137 | | -
|
138 | | -To add |
139 | | -- an **affiliate** project, add `affiliate: true` to the project entry |
140 | | -- a **core** project, add `core: true` to the project entry |
141 | | - |
142 | | -### Adding a page |
143 | | - |
144 | | -To add a page, |
145 | | - |
146 | | -1. Create a directory in the root of the project, with at least an `index.html` file in that directory. |
147 | | -2. Update `_data/nav.yml` to add it to the navigation. (The site navigation is not fully dynamic for simplification.) |
| 59 | +## Development |
148 | 60 |
|
149 | | -Sample front matter for a page: |
| 61 | +The build machinery is defined in `build.scala`. It implements several customizations, including an RSS feed generator and integrations with Protosearch, KaTeX, and Font Awesome. |
150 | 62 |
|
151 | | -```yml |
152 | | -layout: page |
153 | | -title: "Code of Conduct" |
154 | | -``` |
| 63 | +To learn more about how you can develop and customize the website please reference the extensive [Laika] documentation. |
155 | 64 |
|
156 | | -### Help, CI is failing on a Dependabot PR |
| 65 | +## Support |
157 | 66 |
|
158 | | -We need to update the gemset as well. |
| 67 | +We are happy to help you contribute to our website! Please [create a discussion][discussion] or message the [#website][discord] channel on the Typelevel Discord. |
159 | 68 |
|
160 | | -```sh |
161 | | -nix run nixpkgs#bundix |
162 | | -git commit -am "Update gemset" |
163 | | -``` |
| 69 | +[Laika]: https://typelevel.org/Laika |
| 70 | +[syntax]: https://typelevel.org/Laika/latest/03-preparing-content/05-syntax-highlighting.html#supported-languages |
| 71 | +[gfm]: https://github.github.com/gfm/ |
| 72 | +[discussion]: https://github.com/typelevel/typelevel.github.com/discussions/new/choose |
| 73 | +[discord]: https://discord.gg/krrdNdSDFf |
0 commit comments