jekyll-theme-alta-docs 0.1.0 → 0.2.0

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 3873a9954922eaeb24f017eb8c908060e15d081a02de0341541f6f7feb0ffe67
4
- data.tar.gz: fa852d667773d70c1bfe26207e894d548f49821abb63e75cbf602e661c332098
3
+ metadata.gz: e66de8ee1a3d8de337c6ab2214b84461339547390700443763ec32669f12e1ac
4
+ data.tar.gz: 407c33116e63d462aab77409f8161c614e189141565b4d6d690c2bf03581f007
5
5
  SHA512:
6
- metadata.gz: 30233e201557158370c7679be7e4659fee78f0b694a2a8b5b7686e7bf92cf006162895f686958431796c41748ede7ddaba358e895a70211997ac28b668ac748a
7
- data.tar.gz: e9c9187bddb2a66ef74a7cca19784d0d291779fa5f4049a1c8795a5df1d63e269f6d092f79f32c48674a3d483c2e739f2f184964a1d88d4a7a2cbb0cf17eeb90
6
+ metadata.gz: 68c991d1a43d1a76c4ed7d4a616f28b7e3efb10e45958d3c361aabf41768b831986bd4a4b9d26fe6840521ad04e5574749d4668bdd9b1455006e3a26537c2b04
7
+ data.tar.gz: b2e2567c5d572a406700f28e9fa91902ad5d60b15a1c98a3f18824aad5ffb1f50c9dc0da6d309c891b99fde090d3cf4e8fcc4ebb1af122e533e838800ea38710
data/README.md CHANGED
@@ -1,24 +1,111 @@
1
1
  # Jekyll Theme: Alta Docs Theme
2
2
 
3
- The Jekyll theme for documenting development projects.
3
+ The Jekyll theme for documenting software development projects.
4
+
5
+ ![Screenshot](screenshot.png)
4
6
 
5
7
  ## Basic usage
6
8
 
7
- 1. Add the theme to the `Gemfile`
8
- ```
9
- gem "jekyll-theme-alta-docs"
10
- ```
9
+ ### New Jekyll project
10
+
11
+ 1. Install Jekyll
12
+
13
+ gem install bundler jekyll
14
+
15
+ 2. Create Jekyll project:
16
+
17
+ jekyll new my-project
18
+
19
+ 3. Go to the project:
20
+
21
+ cd my-project
22
+
23
+ 4. Run:
11
24
 
12
- 2. Run `bundle install`
25
+ bundle exec jekyll serve
26
+ # OR
27
+ bundle exec jekyll serve --host xxx.xx.xxx.xx --port 4001
13
28
 
14
- 3. Add `index.html` page to the root directory (the *Getting started* page).
29
+ ### Use jekyll-theme-alta-docs
15
30
 
16
- 4. Create a folder your *docs* collection, i.e. `_docs/`
31
+ 1. Change `Gemfile`
17
32
 
18
- 5. Set up the `_config.yml`
33
+ # gem "minima", "~> 2.5" # <-- Remove or comment
34
+ gem "jekyll-theme-alta-docs" # <--- Add
19
35
 
36
+ 2. Run:
37
+
38
+ $ bundle install
39
+
40
+ 3. Create *_docs/* folder
41
+
42
+ 4. Edit `_config.yml`:
43
+
44
+ # Set new theme:
45
+ theme: jekyll-theme-alta-docs
46
+
47
+ # Register new collection "docs" from "_docs" folder:
48
+ collections:
49
+ docs:
50
+ output: true
51
+ permalink: /:collection/:name/
52
+
53
+ # Bind your "docs" collection
20
54
  doc_collection : docs
21
- doc_version : 1.0.0
55
+
56
+ 5. Add markdown files to the `_docs/` folder:
57
+
58
+ # _docs/01_intro/getting_started.md
59
+ ---
60
+ title: Getting started # Enter any name
61
+ category: Intro # Enter any category. Categories are used to group docs.
62
+ layout: doc # Important! Use doc layout
63
+ toc: true # Optional: to display table of contents
64
+ order: 11 # To sort the documents in the navigation
65
+ ---
66
+
67
+ ## Getting started
68
+
69
+ Hello world!
70
+
71
+ 6. Add `index.md` in the root directory (Home page):
72
+
73
+ # index.md
74
+ ---
75
+ layout: page
76
+ ---
77
+
78
+ # Home page
79
+
80
+ This is my home page
81
+
82
+ 7. Run:
83
+
84
+ bundle exec jekyll serve
85
+
86
+ ### What's next?
87
+
88
+ Add more documents in *_docs* folder and see [advanced options](#advanced-options).
89
+
90
+
91
+ ## Advanced options
92
+
93
+ ### Common _config.yml options
94
+
95
+ title : "Project title"
96
+
97
+ getting_started : >- # Used in the Project overview component
98
+ Take a look on the useful materials below.
99
+ Start by checking "the System Overview" to get a big picture of the project.
100
+ Don't forget to check "Development Guidelines".
101
+ Find more by exploring navigation on the left.
102
+
103
+
104
+
105
+ ### Links
106
+
107
+ Links to the repositories can be added in *_config.yml*:
108
+
22
109
  links:
23
110
  repos:
24
111
  - name : Web app repository
@@ -30,6 +117,76 @@ gem "jekyll-theme-alta-docs"
30
117
  - name : Docs repository
31
118
  icon : "fab fa-gitlab" # Use fontawesome v6
32
119
  url : https://bitbucket.org/
120
+ useful:
121
+ - name : System overview
122
+ icon : "fas fa-project-diagram"
123
+ url : /architecture/
124
+ - name : Architecture
125
+ icon : "fas fa-clipboard-list"
126
+ url : /architecture/
127
+ - name : Development Guidelines
128
+ icon : "fas fa-pencil-alt"
129
+ url : /architecture/
130
+
131
+ Repositories links are displayed in website footer.
132
+
133
+
134
+ ### System components
135
+
136
+ You can define the system components like Backend, Frontend etc. in *_config.yml*:
137
+
138
+ system_components:
139
+ - name : Frontend
140
+ techs :
141
+ - name: React.js
142
+ - name: Redux
143
+ - name : Backend
144
+ techs :
145
+ - name: Ruby on Rails
146
+ - name : Database
147
+ techs :
148
+ - name: PostgreSQL
149
+ - name : Service provider
150
+ techs :
151
+ - name: AWS
152
+
153
+ The "System components" are used in two components:
154
+
155
+ * `project_overview.html` > `{% include project_overview.html %}`
156
+ * `system_components_overview.html` > `{% include project_overview.html %}`
157
+
158
+
159
+ ### Versioning
160
+
161
+ The documentation version is displayed in the footer.
162
+
163
+ doc_version : 1.0.0
164
+
165
+
166
+ ## Components (includes)
167
+
168
+ ### Project overview
169
+
170
+ The "Project overview" component renders:
171
+
172
+ * `project_title`
173
+ * `doc_version`
174
+ * `description`
175
+ * `getting_started`
176
+ * `system_components`
177
+ * `links`
178
+
179
+ Props:
180
+
181
+ * `next_button` - URL for the "Get started!" button
182
+
183
+ Usage:
184
+
185
+ {% include project_overview.html next_button="/docs/development/" %}
186
+
187
+ Example:
188
+
189
+ ![Project overview](docs/project_overview.png)
33
190
 
34
191
 
35
192
  ## Development
@@ -38,6 +195,7 @@ To set up your environment to develop this theme, run `bundle install`.
38
195
 
39
196
  To test theme, run: `bundle exec rake preview` or `bundle exec rake preview host=xxx.xx.xxx.xx`
40
197
 
198
+
41
199
  ## License
42
200
 
43
201
  The theme is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
@@ -10,7 +10,7 @@
10
10
  </ul>
11
11
  </div>
12
12
  <div class="ad-page__subfooter-content">
13
- <span>{{ site.project_name }}, {{ site.doc_version }}</span>
13
+ <span>{{ site.title }}, {{ site.doc_version }}</span>
14
14
  </div>
15
15
  </div>
16
16
  </footer>
@@ -1,5 +1,5 @@
1
1
  <div class="ad-page__navbar">
2
2
  <div class="ad-page__navbar-content container">
3
- <span class="nav-brand">{{ site.project_name }}</span>
3
+ <span class="nav-brand">{{ site.title }}</span>
4
4
  </div>
5
5
  </div>
@@ -0,0 +1,41 @@
1
+ <div class="ad-project-overview container">
2
+ <div class="ad-project-overview__header">
3
+ <h1>{{ site.title }}</h1>
4
+ <span class="ad-project-overview__version">{{ site.doc_version }}</span>
5
+ {% if site.description %}
6
+ <p class="ad-project-overview__site-description">{{ site.description }}</p>
7
+ {% endif %}
8
+ </div>
9
+
10
+ <div class="ad-project-overview__content">
11
+ <div class="ad-page-section">
12
+ <h2><span class="symbol">&#128640;</span> Getting started</h2>
13
+ {% if site.getting_started %}
14
+ <p>{{ site.getting_started }}</p>
15
+ {% endif %}
16
+ </div>
17
+
18
+ {% if site.system_components %}
19
+ <div class="ad-page-section">
20
+ <h3><span class="symbol">&#128736;</span> System components</h3>
21
+ {% include system_components_overview.html %}
22
+ </div>
23
+ {% endif %}
24
+
25
+ {% if site.links %}
26
+ <div class="ad-page-section">
27
+ <h3><span class="symbol">&#128279;</span> Links</h3>
28
+ {% include useful_links.html %}
29
+ </div>
30
+ {% endif %}
31
+
32
+
33
+ {% if include.next_button %}
34
+ <hr />
35
+ <div class="ad-project-overview__next-button">
36
+ <a href="{{ include.next_button }}" class="ad-btn-primary btn-lg">Get started!</a>
37
+ </div>
38
+ {% endif %}
39
+
40
+ </div>
41
+ </div>
@@ -0,0 +1,12 @@
1
+ <div class="ad-system_components">
2
+ {% for component in site.system_components %}
3
+ <div class="ad-system_component">
4
+ <span class="name">{{ component.name }}</span>
5
+ <ul>
6
+ {% for tech in component.techs %}
7
+ <li>{{ tech.name }}</li>
8
+ {% endfor %}
9
+ </ul>
10
+ </div>
11
+ {% endfor %}
12
+ </div>
@@ -0,0 +1,20 @@
1
+ <div class="ad-useful-links">
2
+ <div class="ad-useful-links__col">
3
+ <ul>
4
+ {% for link in site.links.useful %}
5
+ <li>
6
+ <a href="{{ link.url }}"><i class="{{ link.icon }}"></i> {{ link.name }}</a>
7
+ </li>
8
+ {% endfor %}
9
+ </ul>
10
+ </div>
11
+ <div class="ad-useful-links__col w-200">
12
+ <ul>
13
+ {% for link in site.links.repos %}
14
+ <li>
15
+ <a href="{{ link.url }}"><i class="{{ link.icon }}"></i> {{ link.name }}</a>
16
+ </li>
17
+ {% endfor %}
18
+ </ul>
19
+ </div>
20
+ </div>
@@ -2,11 +2,14 @@
2
2
 
3
3
  $primary-color: #8600E8;
4
4
  $dark-color: #142233;
5
+ $gray-200: #F1F5F9;
5
6
  $gray-400: #DFE5EC;
6
7
  $text-color-primary: $dark-color;
7
8
  $text-color-regular: #3E546B;
8
9
  $link-color: #8905EA;
9
10
  $link-color-hover: #6109A1;
11
+ $header-bg: #f4f7fd;
12
+ $code-bg: #f4f7fd;
10
13
  $font-family-primary: 'Poppins', sans-serif;
11
14
  $font-family-regular: 'Source Sans Pro', sans-serif;
12
15
 
@@ -61,6 +64,71 @@ a.ad-btn-nav-home {
61
64
  }
62
65
  }
63
66
 
67
+ .ad-btn-default {
68
+ @include shadow(0.05);
69
+ font-family: $font-family-primary;
70
+ background: transparent;
71
+ border: 1px solid $link-color;
72
+ border-radius: 5px;
73
+ padding: 5px 10px;
74
+ &:hover {
75
+ border-color: $link-color-hover;
76
+ color: $link-color-hover;
77
+ }
78
+ }
79
+
80
+ .ad-btn-primary {
81
+ @include shadow(0.2);
82
+ font-family: $font-family-primary;
83
+ background: $link-color;
84
+ border: 1px solid $link-color;
85
+ border-radius: 5px;
86
+ color: #fff;
87
+ padding: 5px 10px;
88
+ &:hover {
89
+ background: $link-color-hover;
90
+ color: #fff;
91
+ }
92
+ }
93
+
94
+ .btn-lg {
95
+ font-size: 20px;
96
+ font-weight: 600;
97
+ font-family: $font-family-primary;
98
+ padding: 10px 15px;
99
+ }
100
+
101
+ .primary-color {
102
+ color: $primary-color;
103
+ }
104
+
105
+ h1 {
106
+ i.fas, .symbol {
107
+ font-size: 20px;
108
+ margin-right: 7px;
109
+ }
110
+ }
111
+
112
+ h2 {
113
+ i.fas, .symbol {
114
+ font-size: 16px;
115
+ margin-right: 5px;
116
+ }
117
+ }
118
+
119
+ h3 {
120
+ i.fas, .symbol {
121
+ font-size: 14px;
122
+ margin-right: 5px;
123
+ }
124
+ }
125
+
126
+ hr {
127
+ height: 1px;
128
+ background-color: $gray-400;
129
+ border: none;
130
+ }
131
+
64
132
  .container {
65
133
  max-width: 1200px;
66
134
  margin-left: auto;
@@ -87,7 +155,7 @@ a.ad-btn-nav-home {
87
155
  }
88
156
  .ad-page__content {
89
157
  width: 100%;
90
-
158
+
91
159
  padding: 15px;
92
160
  -webkit-box-sizing: border-box;
93
161
  -moz-box-sizing: border-box;
@@ -229,7 +297,7 @@ button.ad-collapsible, .ad-collapsible {
229
297
 
230
298
  .ad-doc__header {
231
299
  border-bottom: 1px solid #f3f3f3;
232
- background: #f4f7fd;
300
+ background: $header-bg;
233
301
  padding: 30px;
234
302
 
235
303
  h1 {
@@ -279,8 +347,102 @@ button.ad-collapsible, .ad-collapsible {
279
347
  }
280
348
  }
281
349
 
350
+ .ad-project-overview {
351
+ .ad-project-overview__header {
352
+ padding: 30px;
353
+ background: $header-bg;
354
+ h1 {
355
+ margin-bottom: 5px;
356
+ }
357
+ .ad-project-overview__version {
358
+ opacity: 0.3;
359
+ font-size: 12px;
360
+ }
361
+ .ad-project-overview__site-description {
362
+ color: $text-color-regular;
363
+ opacity: 0.5;
364
+ }
365
+ }
366
+ }
367
+
368
+ .ad-page-section {
369
+ padding-top: 15px;
370
+ padding-bottom: 15px;
371
+ }
372
+
373
+ .ad-system_components {
374
+ display: flex;
375
+ align-items: stretch;
376
+ justify-content: flex-start;
377
+ flex-wrap: wrap;
378
+ .ad-system_component {
379
+ min-width: 200px;
380
+ flex: 1;
381
+ display: flex;
382
+ flex-direction: column;
383
+ border: 1px solid $gray-200;
384
+ padding: 5px;
385
+
386
+ .name {
387
+ font-family: $font-family-primary;
388
+ font-weight: bold;
389
+ text-transform: uppercase;
390
+ font-size: 12px;
391
+ }
392
+ ul {
393
+ list-style: none;
394
+ padding-left: 5px;
395
+ margin-top: 3px;
396
+ margin-bottom: 3px;
397
+ font-size: 12px;
398
+ }
399
+ }
400
+ }
401
+
402
+ .ad-useful-links {
403
+ display: flex;
404
+ flex-wrap: wrap;
405
+ .ad-useful-links__col {
406
+ flex: 1;
407
+ border-right: 1px solid $gray-400;
408
+ &:last-child {
409
+ border-width: 0;
410
+ }
411
+
412
+ &.w-200 {
413
+ width: 200px;
414
+ min-width: 200px;
415
+ max-width: 200px;
416
+ }
417
+
418
+ ul {
419
+ list-style: none;
420
+ margin: 3px 0;
421
+ padding-left: 0;
422
+ li {
423
+ padding: 2px 5px;
424
+ a {
425
+ font-size: 16px;
426
+ i {
427
+ min-width: 16px;
428
+ text-align: center;
429
+ margin-right: 3px;
430
+ font-size: 11px;
431
+ }
432
+ }
433
+ }
434
+ }
435
+ }
436
+ }
437
+
438
+ .ad-project-overview__next-button {
439
+ padding-top: 40px;
440
+ padding-bottom: 40px;
441
+ text-align: center;
442
+ }
443
+
282
444
  code.highlighter-rouge {
283
- background: #f4f7fd;
445
+ background: $code-bg;
284
446
  padding: 1px 3px;
285
447
  border-radius: 2px;
286
448
  color: #e00bbc;
@@ -288,7 +450,7 @@ code.highlighter-rouge {
288
450
 
289
451
  pre.highlight {
290
452
  padding: 10px;
291
- background: #f4f7fd;
453
+ background: $code-bg;
292
454
  border: 1px solid $gray-400;
293
455
  border-radius: 3px;
294
456
  .k {
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: jekyll-theme-alta-docs
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.0
4
+ version: 0.2.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Tom Antas
@@ -94,8 +94,11 @@ files:
94
94
  - _includes/head_scripts.html
95
95
  - _includes/nav.html
96
96
  - _includes/navbar.html
97
+ - _includes/project_overview.html
97
98
  - _includes/scripts.html
98
99
  - _includes/sidebar.html
100
+ - _includes/system_components_overview.html
101
+ - _includes/useful_links.html
99
102
  - _layouts/default.html
100
103
  - _layouts/doc.html
101
104
  - _layouts/page.html
@@ -124,5 +127,5 @@ requirements: []
124
127
  rubygems_version: 3.0.3
125
128
  signing_key:
126
129
  specification_version: 4
127
- summary: Dev docs theme.
130
+ summary: The Jekyll theme for documenting software development projects..
128
131
  test_files: []