jekyll-theme-alta-docs 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
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: []