README.md 7.63 KB
Newer Older
Robert Speicher's avatar
Robert Speicher committed
1
# www-gitlab-com
Robert Speicher's avatar
Robert Speicher committed
2

Ernst van Nierop's avatar
Ernst van Nierop committed
3
This is the source for the https://about.gitlab.com/ site. For a guide on how to start editing the website using git, see the [handbook page on that topic](https://about.gitlab.com/handbook/git-page-update).
Robert Speicher's avatar
Robert Speicher committed
4

5
6
## Local development

7
[Read how to preview any changes locally.](doc/development.md)
8

Robert Speicher's avatar
Robert Speicher committed
9
10
## Contributing

11
12
Please see the [contribution guidelines](CONTRIBUTING.md)

Robert Speicher's avatar
Robert Speicher committed
13
14
15
16
17
### Adding yourself to the team page

Edit [`data/team.yml`](./data/team.yml) and add a new entry for yourself (or
update the placeholder with your initials).

masOOd's avatar
masOOd committed
18
Images should be square and should be uploaded to [`source/images/team`](./source/images/team).
Robert Speicher's avatar
Robert Speicher committed
19
20
21
22
23
24
25

### Adding a pet to the team pets page

Edit [`data/pets.yml`](./data/pets.yml) and add a new entry.

Images should be uploaded to [`source/images/team/pets`](./source/images/team/pets).

26
### Blog posts
27

28
[Read how to add a blog post.](doc/blog-posts.md)
29

30
### Adding an application to the applications page (under `/applications`)
31

32
[How to add an application.](doc/applications.md)
33

Robert Speicher's avatar
Robert Speicher committed
34
35
36
37
38
39
40
41
### Updating the promotion link

This link appears at the top of the homepage and can be used to promote new
versions or upcoming events.

Edit [`data/promo.yml`](./data/promo.yml) to update the `link` and `text`
properties.

Régis Freyd (GitLab)'s avatar
Régis Freyd (GitLab) committed
42
### Update the features page (under `/features`)
43

44
[How to update the features page.](doc/features.md#update-the-features-page-under-features)
45

46
### Create or update the comparison pages (under `/comparison`)
Régis Freyd (GitLab)'s avatar
Régis Freyd (GitLab) committed
47

48
[How to update the comparison pages.](doc/features.md#create-or-update-the-comparison-pages-under-comparison)
49

50
### Update the releases page (under `/releases`)
51

52
[How to update the releases page.](doc/releases.md)
Régis Freyd (GitLab)'s avatar
Régis Freyd (GitLab) committed
53

54
55
### Update the projects page (under `/handbook/engineering/projects`)

56
[How to update the projects page.](doc/projects.md)
57

58
### Press releases page
59

60
[How to add a press release page.](doc/press.md)
61

62
## PDF files
63

64
[How to work with PDFs.](doc/pdf.md)
65

Régis Freyd (GitLab)'s avatar
Régis Freyd (GitLab) committed
66
67
68
## Production build

Before building the static files, ensure you have a GitLab.com `PRIVATE_TOKEN`
masOOd's avatar
masOOd committed
69
environment variable set up. This is required so that the Middleman can automatically
Régis Freyd (GitLab)'s avatar
Régis Freyd (GitLab) committed
70
71
72
73
74
75
76
77
78
79
80
build the [direction page](https://about.gitlab.com/direction/).

```sh
bundle install
bundle exec rake build
# To also build PDFs:
bundle exec rake pdfs
```

The above command builds the static files and PDFs into the folder `public`.

81
82
83
84
85
Due to the number of API requests necessary for generating the Direction page,
the results of those requests are cached for 36 hours. If you need the page to
be updated earlier than that, provide the `CLEAR_DIRECTION_CACHE` [environment
variable](https://docs.gitlab.com/ee/ci/pipelines.html#manually-executing-pipelines).

86
## Custom Generators
87

88
There are a few custom, static generators specified in `config.rb`. For
masOOd's avatar
masOOd committed
89
example, some generators produce the direction issue list,
90
releases list, and organization chart dynamically.
91
92
93
94

These pages cannot be viewed directly via the Middleman server
(e.g. http://localhost:4567) because there are explicit rules that
tell Middleman to defer the generation to other scripts. These
95
special URLs (e.g. /releases/index.html) usually have two
96
97
98
99
100
101
102
103
Middleman keywords:

1. [`proxy`](https://middlemanapp.com/advanced/dynamic_pages/)

    This tells Middleman to output a static file based on the provided template.

2. [`ignore`](https://www.relishapp.com/middleman/middleman-core/docs/ignoring-paths)

masOOd's avatar
masOOd committed
104
105
    This tells the Middleman server not to handle this URL. The external generator will
    build static files.
106
107
108

To preview these custom-generated pages locally, you must first rebuild the files:

Evan Read's avatar
Evan Read committed
109
```sh
110
bundle exec middleman build
111
112
113
114
115
```

To test out the site, you must run another Web server from the
`public` directory:

Evan Read's avatar
Evan Read committed
116
```sh
Mark Pundsack's avatar
Mark Pundsack committed
117
(cd public; python -m SimpleHTTPServer 8000)
118
119
120
121
122
```

This will start a Web server on port 8000 (you may omit the port number). You can preview the site
by pointing your browser to http://localhost:8000.

123
124
125
126
127
128
## Review Apps

Thanks to the [Review Apps], the `www-gitlab-com` project supports live reviewing
of any website changes with every merge request. When a branch is pushed and
the pipeline is successfully run, you can see a link pointing to the live
environment in your merge request. The URL will be of the following scheme:
129
130
`<branch-name>.about.gitlab.com`.  Note that if you have underscores in your
branch name, they will be replaced with dashes in the URL.
131
132
133
134
135
136
137
138

Beware that:

- To successfully deploy a Review App, the branch must exist in the
  `www-gitlab-com` repository. That means that branches from forks will not
  deploy a Review App (hence MRs from contributors). For that case, you should
  have at least Developer access to the `www-gitlab-com` project or
  `gitlab-com` group.
masOOd's avatar
masOOd committed
139
- The generation of the direction, wishlist, and releases pages are omitted
140
141
142
  in branches and is run only on master. This helps to shave off some time from
  the build process. That means you won't be able to preview these pages with
  Review Apps.
143
144

[review apps]: https://docs.gitlab.com/ce/ci/review_apps/
Sid Sijbrandij's avatar
Sid Sijbrandij committed
145

Fabio's avatar
Fabio committed
146
147
148
## Use Docker to render the website

If you don't have a proper environment available to run Middleman, you can use
masOOd's avatar
masOOd committed
149
Docker to provide one for you locally on your machine. To have this
Fabio's avatar
Fabio committed
150
151
152
153
working correctly, you need to have at least Git and Docker installed, and an
internet connection available.

1. Clone the repository in a local folder
Evan Read's avatar
Evan Read committed
154
   ```sh
Fabio's avatar
Fabio committed
155
156
   git clone git@gitlab.com:gitlab-com/www-gitlab-com.git
   ```
Saumya Upadhyaya's avatar
Saumya Upadhyaya committed
157
158
159
160
161
162
163
>  **Note**: If your git clone is timing out, update the ServerAliveInterval in ~/.ssh/config to a larger number. For example, below is the content of the ~/.ssh/config file. <br> 
> ```
> Host *
>    ServerAliveInterval 1200
>    TCPKeepAlive yes 
>    IPQoS=throughput
>```
164

Fabio's avatar
Fabio committed
165
2. Create a Docker container
Evan Read's avatar
Evan Read committed
166
   ```sh
Fabio's avatar
Fabio committed
167
   docker create --name middleman -v "$PWD/www-gitlab-com":/site -w /site -p 4567:4567 \
168
     -e LC_ALL=C.UTF-8 ruby /bin/bash -c 'gem install bundler && bundle install && bundle exec middleman'
Fabio's avatar
Fabio committed
169
   ```
170

Fabio's avatar
Fabio committed
171
3. Start the container
Evan Read's avatar
Evan Read committed
172
   ```sh
Fabio's avatar
Fabio committed
173
174
175
   docker start middleman
   ```

Evan Read's avatar
Evan Read committed
176
4. Connect to http://localhost:4567
Fabio's avatar
Fabio committed
177

Saumya Upadhyaya's avatar
Saumya Upadhyaya committed
178
> **Note**: You won't be able to connect immediately. Middleman takes a few minutes to render the site. Run docker ps -ls to see if middleman is still running.
179

Fabio's avatar
Fabio committed
180
181
182
5. Change your original content as usual, and see the changes in the browser as soon as
you save the new version of the file (otherwise, just restart the container)

183
6. When you have finished, stop the container
Evan Read's avatar
Evan Read committed
184
   ```sh
Fabio's avatar
Fabio committed
185
186
187
188
189
   docker stop middleman
   ```

> **Note**: Subsequent runs will just require `docker start middleman`.

190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
## Building a single file

If you only want Middleman to build a single file, you can do that via the `--glob` parameter.
Here are a few things to keep in mind:

* The glob parameter must match the **destination** file.

* The `--no-clean` option should be included or Middleman will wipe out
  files that do not match the glob parameter.

For example, here's how to rebuild the Contribute page. Note how
`source/company/culture/index.html.md.erb` is mapped to
`company/culture/contribute/index.html`:

```sh
bundle exec middleman build --glob={company/culture/contribute/index.html} --no-clean
```

For blog posts,
`source/posts/2017-05-23-attributes-of-successful-development-teams.html.md`
maps to `2017/05/23/attributes-of-successful-development-teams/index.html`:

```sh
bundle exec middleman build --glob={2017/05/23/attributes-of-successful-development-teams/index.html} --no-clean
```
Stan Hu's avatar
Stan Hu committed
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231

## Conclusion (please leave this at the bottom of the doc)

In case someone forgot the most important commands and is catting this file from the command line we end by listing them:

```sh
kill -kill `lsof -t -i tcp:4567`
bundle exec rake new_post
open -a "Google Chrome" http://localhost:4567
bundle exec middleman
```

or to execute the last two commands just run:

```sh
bin/run
```