You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: doc/_doc-guide/01_Structure/README.md
+97-24
Original file line number
Diff line number
Diff line change
@@ -14,79 +14,152 @@ Basically we follow [[jekyll|jekyll-dir-struct]] and [[minimal-mistake|mm-dir-st
14
14
│ navigation.yml
15
15
│ excluded_titles.yml
16
16
│ external_links.yml
17
-
│
18
-
├── _js
19
-
│ ├── custom
20
-
│ ├── plugins
21
-
│ ├── vendor
22
-
│ _main.js
17
+
│ link_aliases.yml
23
18
│
24
19
├── _includes
25
20
│ ├── footer
26
21
│ ├── head
27
22
│ ...
28
23
│ └── search
29
24
│
25
+
├── _js
26
+
│ ├── custom
27
+
│ ├── plugins
28
+
│ ├── vendor
29
+
│ _main.js
30
+
│
30
31
├── _layouts
32
+
│
33
+
├── _plugins
34
+
│
31
35
├── _sass
32
36
│ └── minimal-mistakes
37
+
│
38
+
├── .github
39
+
│ └── workflows
40
+
│
33
41
├── _site
42
+
│
34
43
├── _tools
44
+
│
35
45
├── assets
36
46
│ ├── css
37
47
│ ├── images
38
48
│ └── js
49
+
│
39
50
├── doc
40
51
│ ├── _admin-guide
41
52
│ ├── _dev-guide
42
-
│ └── _doc-guide
53
+
│ ├── _doc-guide
54
+
│ └── site-internal
43
55
│
44
56
_config.yml
45
57
Gemfile
46
-
LICENSE.midnight
47
-
LICENSE.minimal-mistakes
58
+
LICENSE.*
48
59
README.md
49
60
```
50
61
51
62
### Directories
52
63
53
-
-_data
64
+
-_data \
65
+
Contains further `_site` generation input files for navigation, link generation, exclusion, etc.
54
66
- links \
55
67
<u>DO NOT USE!!!</u> \
56
-
It lives only during jekyll serving_site data, excluded from git via `.gitignore`\
57
-
It is built based the content of the `doc` folder
68
+
It lives only during jekyll generatig the_site data, excluded from git via `.gitignore`\
69
+
It is built based the content of the `doc` folder and contains files used for autolink/tooltip generation.
58
70
59
71
-_includes \
72
+
This folder contains reusable and/or common html and liquid codes the final `_site` pages are using.
60
73
61
-
-_js\
74
+
-_js
62
75
- custom \
63
-
To stay organized, please keep our custom scripts in this folder.
64
-
76
+
To stay organized, please keep our custom js scripts in this folder.
77
+
- plugins
78
+
- vendor
79
+
3rd party js scripts used mainly by minimal-mistakes, but also keeps dependencies of our modifications as well.
80
+
- lunr
81
+
lunr is also a 3rd party dependency, it is now the default search engine, and we have a slighty modified version of its `lunr-en.js`
65
82
-_layouts \
83
+
The main layout files the final `_site` pages are based on. Only the really used layouts are kept, all the other default minimal-mistakes layouts wre removed.
66
84
67
85
-_sass \
86
+
The Jekyll Sass converter input files, container of all the styles related sheets, except the main sheet files.
68
87
69
88
-_site \
89
+
<u>DO NOT USE!!!</u> \
90
+
This is the generated static `_site` content container, the content of this foler will be the final HTML site.\
91
+
Excluded from git via `.gitignore`\
70
92
71
93
-_tools \
94
+
This folder contains our [[self-made helper tools|doc-own-tools]].
95
+
96
+
- .github
97
+
- workflows \
98
+
The [[GitHub CI build Action|gh-syslog-ng-doc-actions]] workflow files.
72
99
73
-
- assets \
74
-
- css
75
-
- images
100
+
- assets
101
+
- css \
102
+
The `_site` main style sheet definition files which include the content of the `_sass` folder and serve as style sheet files for skinning as well. \
103
+
See comments in `main.scss` for more.
104
+
- images \
105
+
The `_site` image files collector folder, please keep all the used images here, and try keep them organized mainly on their collection membership.
76
106
- js \
77
107
<u>DO NOT USE!!!</u> \
78
-
It lives only during jekyll serving _site data, excluded from git via `.gitignore`\
108
+
It lives only during jekyll serving `_site` data, excluded from git via `.gitignore`\
79
109
It is built from the content of the `_js` folder
80
110
81
111
- doc \
112
+
This folder contains the real content, the markdwon files, of a given documentation collection.
113
+
-_admin-guide \
114
+
Markdown source files of The syslog-ng OSE Administration Guide
115
+
-_dev-guide \
116
+
Markdown source files of the [[Developer Guide|dev-guide]]
117
+
-_doc-guide \
118
+
Markdown source files of the [[Documentation Guide|doc-guide]]
119
+
- site-internal \
120
+
Markdown and HTML source files of the none collection, mainly `_site` common, pages like the 404 page.
82
121
83
122
### Files
84
123
85
124
-_config.yml \
86
-
[[Jekyll configuration|jekyll-config]] file
125
+
Our[[Jekyll configuration|jekyll-config]] file
87
126
- Gemfile \
88
-
Jekyll and minimal-mistake [[Ruby gem|jekyll-ruby-gems]] dependencies
89
-
- README.md \
90
-
The project [[GitHub repository|gh-syslog-ng-doc]] landing page readme file
127
+
Jekyll and minimal-mistake [[Ruby gem|jekyll-ruby-gems]] dependencies
91
128
- LICENSE.*\
92
-
All the licence files of the modules the project uses
129
+
All the licence files of the modules the project uses
130
+
- README.md \
131
+
The project [[GitHub repository|gh-syslog-ng-doc]] landing page readme file
132
+
-_data/navigation.yml \
133
+
The input yaml file of the left navigation sidebar, this is generated by the navgen tool (DO NOT EDIT, your edits will be overwritten!).
134
+
-_data/excluded_titles.yml \
135
+
A list of sentences that will be excluded from the autolink/tooltip generation.
136
+
-_data/external_links.yml \
137
+
Collector of all the external links we are referencing in our pages, please keep all none site cross links here.
138
+
-_data/link_aliases.yml \
139
+
A link ID based collection of alias sentences that will produce the same autolink/tooltip.
140
+
- .github/workflows/jekyll-gh-pages.yml \
141
+
The GitHub CI Action site builder Workflow file.
142
+
-_js/main.min.js \
143
+
All of our separate js script files (that not embedded into HTML pages) [[pack]]ed into a min.js file, except lunr files, see bellow. (DO NOT EDIT, your edits will be overwritten!)
144
+
-_js/lunr/lunr-en.js \
145
+
This is a bit modified version of the lunr script that actually generates the search result output, we use a simplfied search method, actually we reverted back from the minimal-mistakes version to the original, default one described in the lunr help.
146
+
-_plugins/common_includes.rb \
147
+
A Jekyll pre_render pass plugin that inserts our common inlude files into each markdown page
148
+
-_plugins/[[generate_links]].rb \
149
+
A Jekyll post_render pass plugin that generates the input link files for autolink/tooltip.
150
+
-_plugins/[[generate_tooltips]].rb \
151
+
A Jekyll pre_render pass plugin that generates the autolink/tooltip HTML code based on link output files of generate_links.rb and our custom markdwon extension.
152
+
-_plugins/[[liquify]].rb \
153
+
A Jekyll liquid filter plugin that can force the evaluation of a liquid expression.
154
+
-_tools/banner.js \
155
+
A js script that adds a DO NOT EDIT banner to a given script file.
156
+
-_tools/[[linkcheck]]\
157
+
A shell script that checks the validity and availability of the link URLs in a given link file, usually in our external_links.yml
158
+
-_tools/[[navgen]]\
159
+
A shell script that generates the input navigation.yml file of our left navigation sidebar from the page titles
160
+
-_tools/[[pack]]\
161
+
A shell script that produces the packed main.min.js file.
162
+
-_tools/package.json.in \
163
+
The input json template file of the pack tool.
164
+
-_tools/[[serve]]\
165
+
A `jekyll serve` wrapper with multiple additional features.
0 commit comments