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: README.md
+35-6Lines changed: 35 additions & 6 deletions
Original file line number
Diff line number
Diff line change
@@ -1,18 +1,45 @@
1
-
#Maintainging the utPLSQL Website
1
+
#Maintaining the utPLSQL Website
2
2
3
-
**TODO - needs rewrite**
4
3
5
-
The[utPLSQL website](https://utplsql.github.io) is powered by[Jekyll](https://jekyllrb.com/). Which generated HTML when you push a commit to[utplsql.github.io](https://github.com/utPLSQL/utPLSQL.github.io).
4
+
The[utPLSQL website](https://utplsql.github.io) is generated using[MkDocs](https://www.mkdocs.org/) and[material theme](https://squidfunk.github.io/mkdocs-material)
5
+
[Mike](https://github.com/jimporter/mike) is used for versioning of documentation see also[this page](https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/)
6
6
7
-
This also works in harmony with the gh-pages branches on the various other repository to create a single website. For example the[utpsql](https://github.com/utPLSQL/utPLSQL) repositories[gh-pages](https://github.com/utPLSQL/utPLSQL/tree/gh-pages) branch, is visible at[https://utplsql.github.io/utPLSQL/](https://utplsql.github.io/utPLSQL/).
8
7
9
-
This allows for documentation from each sub repository to host it's own documentation without having to modify the utplsql.github.io repository directly.
8
+
##Local setup
10
9
10
+
You will need to have python installed along with pip (see[this page](https://squidfunk.github.io/mkdocs-material/getting-started/))
11
+
12
+
Once you have pytin and pip installed you will need to install the three components:
13
+
```
14
+
pip install mkdocs-material
15
+
pip install mike
16
+
17
+
```
18
+
19
+
Once installed you can use following commands from command line:
20
+
21
+
`mkdocs serve` - will stat a local server, so you can see the web page generated locally and tet real-time updates to documentation
22
+
`mkdocs gh-deploy` - will deploy changed documentation into repository (if you have privileges).
23
+
24
+
25
+
The generated web pages are hen visible at[utplsql.org](https://utPLSQL.org).
26
+
27
+
Individual project documentation pages are deployed separately from the main organization page.
28
+
Each corresponding project repository needs to have its own gh-pages branch.
29
+
30
+
31
+
utPLSQL-framework repository uses`mike` to deploy documentation for specific project version.
32
+
33
+
Example commands to use are:
34
+
35
+
-`mike deploy develop` - to deploy documentation for develop branch
36
+
-`mike deploy -p develop` - to deploy and push documentation for develop branch
37
+
-`mike deploy -p -u v3.1.12 latest` - to deploy and push documentation for version v3.1.12 and update the`latest` alias to point to that version
11
38
12
39
13
40
##How to make an announcement post.
14
41
15
-
Create a File in the[_posts](https://github.com/utPLSQL/utPLSQL.github.io/tree/master/_posts) directory with the file name of`YYYY-MM-DD-Blog-Post-Name.md`
42
+
Create a File in the[docs/_posts](https://github.com/utPLSQL/utPLSQL.github.io/tree/main/docs/_posts) directory with the file name of`YYYY-MM-DD-Blog-Post-Name.md`
16
43
17
44
This file will be a standard[Markdown file](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) which can be editing with any text editor although there are many offline and online editors for Markdown.
18
45
@@ -27,6 +54,8 @@ The file will also need a YAML Front Matter section at the top of the file.
27
54
28
55
Look at an existing post if you want an example.
29
56
57
+
Add new entry pointing to new announcement file to the`nav` section in`mkdocs.yml`
58
+
30
59
##How to preview site locally
31
60
32
61
Jekyll will allow you to preview the site locally doing the following:
As memorandum of Joel Kallman, on this day utPLSQL launched its new website using different engine.
10
+
11
+
We have moved away from using[Jekyll](https://jekyllrb.com/) with GitHub Pages to host project and organization sites.
12
+
[Jekyll](https://jekyllrb.com/) was simply too much hussle and we used[MkDocs](https://www.mkdocs.org/) to generate offline documentation for utPLSQL that was packaged into the release zip file.
13
+
14
+
So instead of using two different methods, wei will now use only one.[MkDocs](https://www.mkdocs.org/) is now used for both utPSLQL offline and for online organization and project pages.
15
+
16
+
Thanks to wonderful[material](https://squidfunk.github.io/mkdocs-material/) theme and[mike](https://github.com/jimporter/mike)(versioning plugin) for MkDocs you may now enjoy the following new features:
17
+
18
+
- dark & light theme
19
+
- better navigation and menu in utPLSQL documentation
20
+
- documentation version dropdown
21
+
- powerful and fast search within documentation
22
+
23
+
Hopefully, you will like the changes and enhancements. All the permanent links to old site should still be working.