1 # This file is part of NIT ( http://www.nitlanguage.org ).
3 # Licensed under the Apache License, Version 2.0 (the "License");
4 # you may not use this file except in compliance with the License.
5 # You may obtain a copy of the License at
7 # http://www.apache.org/licenses/LICENSE-2.0
9 # Unless required by applicable law or agreed to in writing, software
10 # distributed under the License is distributed on an "AS IS" BASIS,
11 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 # See the License for the specific language governing permissions and
13 # limitations under the License.
15 # Base entities of a nitiwiki.
18 import template
::macro
21 # A Nitiwiki instance.
23 # Nitiwiki provide all base services used by `WikiSection` and `WikiArticle`.
24 # It manages content and renders pages.
26 # Each nitiwiki instance is linked to a config file.
27 # This file show to `nitiwiki` that a wiki is present in the current directory.
28 # Without it, nitiwiki will consider the directory as empty.
32 var config
: WikiConfig
34 # Default config filename.
35 var config_filename
= "config.ini"
37 # Force render on all file even if the source is unmodified.
38 var force_render
= false is writable
41 var verbose_level
= 0 is writable
43 # Delete all the output files.
45 var out_dir
= expand_path
(config
.root_dir
, config
.out_dir
)
46 if out_dir
.file_exists
then out_dir
.rmdir
49 # Synchronize local output with the distant `WikiConfig::rsync_dir`.
51 var root
= expand_path
(config
.root_dir
, config
.out_dir
)
52 var rsync_dir
= config
.rsync_dir
53 if rsync_dir
== "" then
54 message
("Error: configure `wiki.rsync_dir` to use rsync.", 0)
57 sys
.system
"rsync -vr --delete -- {root.escape_to_sh}/ {rsync_dir.escape_to_sh}"
60 # Pull data from git repository.
62 sys
.system
"git pull {config.git_origin.escape_to_sh} {config.git_branch.escape_to_sh}"
65 # Analyze wiki files from `dir` to build wiki entries.
67 # This method build a hierarchical structure of `WikiSection` and `WikiArticle`
68 # based on the markdown source structure.
70 var dir
= expand_path
(config
.root_dir
, config
.source_dir
)
71 root_section
= new_section
(dir
)
72 var files
= list_md_files
(dir
)
84 print
"name: {config.wiki_name}"
85 print
"config: {config.ini_file}"
87 if root_section
.is_dirty
then
88 print
"There is modified files:"
89 var paths
= entries
.keys
.to_a
90 var s
= new DefaultComparator
93 var entry
= entries
[path
]
94 if not entry
.is_dirty
then continue
96 if entry
.has_source
then name
= entry
.src_path
.as(not null)
104 print
"Use nitiwiki --render to render modified files"
106 print
"Wiki is up-to-date"
108 print
"Use nitiwiki --fetch to pull modification from origin"
109 print
"Use nitiwiki --rsync to synchronize distant output"
113 # Display msg if `level <= verbose_level`
114 fun message
(msg
: String, level
: Int) do
115 if level
<= verbose_level
then print msg
118 # List markdown source files from a directory.
119 fun list_md_files
(dir
: String): Array[String] do
120 var files
= new Array[String]
121 var pipe
= new ProcessReader("find", dir
, "-name", "*.{config.md_ext}")
122 while not pipe
.eof
do
123 var file
= pipe
.read_line
124 if file
== "" then break # last line
125 var name
= file
.basename
(".{config.md_ext}")
126 if name
== "header" or name
== "footer" or name
== "menu" then continue
131 if pipe
.status
!= 0 then exit
1
132 var s
= new DefaultComparator
137 # Does `src` have been modified since `target` creation?
139 # Always returns `true` if `--force` is on.
140 fun need_render
(src
, target
: String): Bool do
141 if force_render
then return true
142 if not target
.file_exists
then return true
143 return src
.file_stat
.as(not null).mtime
>= target
.file_stat
.as(not null).mtime
146 # Create a new `WikiSection`.
148 # `path` is used to determine the place in the wiki hierarchy.
149 protected fun new_section
(path
: String): WikiSection do
150 path
= path
.simplify_path
151 if entries
.has_key
(path
) then return entries
[path
].as(WikiSection)
152 var root
= expand_path
(config
.root_dir
, config
.source_dir
)
153 var name
= path
.basename
154 var section
= new WikiSection(self, name
)
155 entries
[path
] = section
156 if path
== root
then return section
157 var ppath
= path
.dirname
158 if ppath
!= path
then
159 var parent
= new_section
(ppath
)
160 parent
.add_child
(section
)
162 section
.try_load_config
166 # Create a new `WikiArticle`.
168 # `path` is used to determine the ancestor sections.
169 protected fun new_article
(path
: String): WikiArticle do
170 if entries
.has_key
(path
) then return entries
[path
].as(WikiArticle)
171 message
("Found article `{path}`", 2)
172 var article
= new WikiArticle.from_source
(self, path
)
173 var section
= new_section
(path
.dirname
)
174 section
.add_child
(article
)
175 entries
[path
] = article
179 # Wiki entries found in the last `lookup_hierarchy`.
180 var entries
= new HashMap[String, WikiEntry]
182 # The root `WikiSection` of the site found in the last `lookup_hierarchy`.
183 var root_section
: WikiSection is noinit
185 # Does a template named `name` exists for this wiki?
186 fun has_template
(name
: String): Bool do
187 return expand_path
(config
.root_dir
, config
.templates_dir
, name
).file_exists
190 # Load a template file as a `TemplateString`.
192 # REQUIRE: `has_template`
193 fun load_template
(name
: String): TemplateString do
194 if not has_template
(name
) then
195 message
("Error: can't load template `{name}`", 0)
198 var file
= expand_path
(config
.root_dir
, config
.templates_dir
, name
)
199 var tpl
= new TemplateString.from_file
(file
)
200 if tpl
.has_macro
("TITLE") then
201 tpl
.replace
("TITLE", config
.wiki_name
)
203 if tpl
.has_macro
("SUBTITLE") then
204 tpl
.replace
("SUBTITLE", config
.wiki_desc
)
206 if tpl
.has_macro
("LOGO") then
207 tpl
.replace
("LOGO", config
.wiki_logo
)
212 # Does a sideblock named `name` exists for this wiki?
213 fun has_sideblock
(name
: String): Bool do
214 name
= "{name}.{config.md_ext}"
215 return expand_path
(config
.root_dir
, config
.sidebar_dir
, name
).file_exists
218 # Load a markdown block with `name` from `WikiConfig::sidebar_dir`.
219 private fun load_sideblock
(name
: String): nullable String do
220 if not has_sideblock
(name
) then
221 message
("Error: can't load sideblock `{name}`", 0)
224 name
= "{name}.{config.md_ext}"
225 var path
= expand_path
(config
.root_dir
, config
.sidebar_dir
, name
)
226 var file
= new FileReader.open
(path
)
227 var res
= file
.read_all
232 # Join `parts` as a path and simplify it
233 fun expand_path
(parts
: String...): String do
236 path
= path
.join_path
(part
)
238 return path
.simplify_path
241 # Transform an id style name into a pretty printed name.
243 # Used to translate ids in beautiful page names.
244 fun pretty_name
(name
: String): String do
245 name
= name
.replace
("_", " ")
246 name
= name
.capitalized
(keep_upper
=true)
251 # A wiki is composed of hierarchical entries.
252 abstract class WikiEntry
254 # `Nitiwiki` this entry belongs to.
259 # Entry internal name.
261 # Mainly used in urls.
264 # Displayed title for `self`.
266 # If `self` is the root entry then display the wiki `WikiConfig::wiki_name` instead.
268 if is_root
then return wiki
.config
.wiki_name
269 return wiki
.pretty_name
(name
)
272 # Is this section rendered from a source document?
274 # Source is an abstract concept at this level.
275 # It can represent a directory, a source file,
276 # a part of a file, everything needed to
277 # extend this base framework.
278 fun has_source
: Bool do return src_path
!= null
280 # Entry creation time.
282 # Returns `-1` if not `has_source`.
283 fun create_time
: Int do
284 if not has_source
then return -1
285 return src_full_path
.as(not null).file_stat
.as(not null).ctime
288 # Entry last modification time.
290 # Returns `-1` if not `has_source`.
291 fun last_edit_time
: Int do
292 if not has_source
then return -1
293 return src_full_path
.as(not null).file_stat
.as(not null).mtime
296 # Entry list rendering time.
298 # Returns `-1` if `is_new`.
299 fun last_render_time
: Int do
300 if is_new
then return -1
301 return out_full_path
.file_stat
.as(not null).mtime
306 # Type of the parent entry.
307 type PARENT: WikiEntry
309 # Parent entry if any.
310 var parent
: nullable PARENT = null
312 # Does `self` have a parent?
313 fun is_root
: Bool do return parent
== null
315 # Children labelled by `name`.
316 var children
= new HashMap[String, WikiEntry]
318 # Does `self` have a child nammed `name`?
319 fun has_child
(name
: String): Bool do return children
.keys
.has
(name
)
321 # Retrieve the child called `name`.
322 fun child
(name
: String): WikiEntry do return children
[name
]
324 # Add a sub-entry to `self`.
325 fun add_child
(entry
: WikiEntry) do
327 children
[entry
.name
] = entry
332 # Breadcrumbs from the `Nitiwiki::root_section` to `self`.
334 # Result is returned as an array containg ordered entries:
335 # `breadcrumbs.first` is the root entry and
336 # `breadcrumbs.last == self`
337 var breadcrumbs
: Array[WikiEntry] is lazy
do
338 var path
= new Array[WikiEntry]
339 var entry
: nullable WikiEntry = self
340 while entry
!= null and not entry
.is_root
do
347 # Sidebar relative to this wiki entry.
348 var sidebar
= new WikiSidebar(self)
350 # Relative path from `wiki.config.root_dir` to source if any.
351 fun src_path
: nullable String is abstract
353 # Absolute path to the source if any.
354 fun src_full_path
: nullable String do
356 if src
== null then return null
357 return wiki
.config
.root_dir
.join_path
(src
)
360 # Relative path from `wiki.config.root_dir` to rendered output.
362 # Like `src_path`, this method can represent a
363 # directory or a file.
364 fun out_path
: String is abstract
366 # Absolute path to the output.
367 fun out_full_path
: String do return wiki
.config
.root_dir
.join_path
(out_path
)
371 # Does `self` have already been rendered?
372 fun is_new
: Bool do return not out_full_path
.file_exists
374 # Does `self` rendered output is outdated?
376 # Returns `true` if `is_new` then check in children.
377 fun is_dirty
: Bool do
378 if is_new
then return true
380 if last_edit_time
>= last_render_time
then return true
382 for child
in children
.values
do
383 if child
.is_dirty
then return true
388 # Render `self` and `children` is needed.
389 fun render
do for child
in children
.values
do child
.render
393 # Template file for `self`.
395 # Each entity can use a custom template.
396 # By default the template is inherited from the parent.
398 # If the root does not have a custom template,
399 # then returns the main wiki template file.
400 fun template_file
: String do
401 if is_root
then return wiki
.config
.template_file
402 return parent
.as(not null).template_file
405 # Header template file for `self`.
407 # Behave like `template_file`.
408 fun header_file
: String do
409 if is_root
then return wiki
.config
.header_file
410 return parent
.as(not null).header_file
413 # Footer template file for `self`.
415 # Behave like `template_file`.
416 fun footer_file
: String do
417 if is_root
then return wiki
.config
.footer_file
418 return parent
.as(not null).footer_file
421 # Menu template file for `self`.
423 # Behave like `template_file`.
424 fun menu_file
: String do
425 if is_root
then return wiki
.config
.menu_file
426 return parent
.as(not null).menu_file
429 # Display the entry `name`.
430 redef fun to_s
do return name
433 # Each WikiSection is related to a source directory.
435 # A section can contain other sub-sections or pages.
439 # A section can only have another section as parent.
440 redef type PARENT: WikiSection
444 var title
= config
.as(not null).title
445 if title
!= null then return title
450 # Is this section hidden?
452 # Hidden section are rendered but not linked in menus.
453 fun is_hidden
: Bool do
454 if has_config
then return config
.as(not null).is_hidden
459 redef fun src_path
: String do
460 if parent
== null then
461 return wiki
.config
.source_dir
463 return wiki
.expand_path
(parent
.as(not null).src_path
, name
)
469 # Custom configuration file for this section.
470 var config
: nullable SectionConfig = null
472 # Does this section have its own config file?
473 fun has_config
: Bool do return config
!= null
475 # Try to load the config file for this section.
476 private fun try_load_config
do
477 var cfile
= wiki
.expand_path
(wiki
.config
.root_dir
, src_path
, wiki
.config_filename
)
478 if not cfile
.file_exists
then return
479 wiki
.message
("Custom config for section {name}", 2)
480 config
= new SectionConfig(cfile
)
485 # Also check custom config.
486 redef fun template_file
do
488 var tpl
= config
.as(not null).template_file
489 if tpl
!= null then return tpl
491 if is_root
then return wiki
.config
.template_file
492 return parent
.as(not null).template_file
495 # Also check custom config.
496 redef fun header_file
do
498 var tpl
= config
.as(not null).header_file
499 if tpl
!= null then return tpl
501 if is_root
then return wiki
.config
.header_file
502 return parent
.as(not null).header_file
505 # Also check custom config.
506 redef fun footer_file
do
508 var tpl
= config
.as(not null).footer_file
509 if tpl
!= null then return tpl
511 if is_root
then return wiki
.config
.footer_file
512 return parent
.as(not null).footer_file
515 # Also check custom config.
516 redef fun menu_file
do
518 var tpl
= config
.as(not null).menu_file
519 if tpl
!= null then return tpl
521 if is_root
then return wiki
.config
.menu_file
522 return parent
.as(not null).menu_file
526 # Each WikiArticle is related to a HTML file.
528 # Article can be created from scratch using this API or
529 # automatically from a markdown source file (see: `from_source`).
533 # Articles can only have `WikiSection` as parents.
534 redef type PARENT: WikiSection
537 var parent
= self.parent
538 if name
== "index" and parent
!= null then return parent
.title
544 # What you want to be displayed in the page.
545 var content
: nullable Writable = null is writable
547 # Create a new article using a markdown source file.
548 init from_source
(wiki
: Nitiwiki, md_file
: String) do
549 src_full_path
= md_file
550 init(wiki
, md_file
.basename
(".{wiki.config.md_ext}"))
554 redef var src_full_path
= null
556 redef fun src_path
do
557 var src_full_path
= self.src_full_path
558 if src_full_path
== null then return null
559 var res
= wiki
.config
.root_dir
.relpath
(src_full_path
)
563 # The page markdown source content.
565 # Extract the markdown text from `source_file`.
567 # REQUIRE: `has_source`.
568 var md
: nullable String is lazy
do
569 if not has_source
then return null
570 var file
= new FileReader.open
(src_full_path
.as(not null))
571 var md
= file
.read_all
576 # Returns true if has source and
577 # `last_edit_date` > 'last_render_date'.
578 redef fun is_dirty
do
579 if super then return true
581 return wiki
.need_render
(src_full_path
.as(not null), out_full_path
)
586 redef fun to_s
do return "{name} ({parent or else "null"})"
589 # The sidebar is displayed in front of the main panel of a `WikiEntry`.
592 # Wiki used to parse sidebar blocks.
593 var wiki
: Nitiwiki is lazy
do return entry
.wiki
595 # WikiEntry this panel is related to.
598 # Blocks are ieces of markdown that will be rendered in the sidebar.
599 var blocks
: Array[Text] is lazy
do
600 var res
= new Array[Text]
601 # TODO get blocks from the entry for more customization
602 for name
in entry
.wiki
.config
.sidebar_blocks
do
603 var block
= wiki
.load_sideblock
(name
)
604 if block
== null then continue
611 # Wiki configuration class.
613 # This class provides services that ensure static typing when accessing the `config.ini` file.
617 # Returns the config value at `key` or return `default` if no key was found.
618 protected fun value_or_default
(key
: String, default
: String): String do
619 return self[key
] or else default
622 # Site name displayed.
624 # The title is used as home title and in headers.
627 # * default: `MyWiki`
628 var wiki_name
: String is lazy
do return value_or_default
("wiki.name", "MyWiki")
632 # Displayed in header.
636 var wiki_desc
: String is lazy
do return value_or_default
("wiki.desc", "")
640 # Url of the image to be displayed in header.
644 var wiki_logo
: String is lazy
do return value_or_default
("wiki.logo", "")
646 # Markdown extension recognized by this wiki.
648 # We allow only one kind of extension per wiki.
649 # Files with other markdown extensions will be treated as resources.
651 # * key: `wiki.md_ext`
653 var md_ext
: String is lazy
do return value_or_default
("wiki.md_ext", "md")
655 # Root directory of the wiki.
657 # Directory where the wiki files are stored locally.
659 # * key: `wiki.root_dir`
661 var root_dir
: String is lazy
do return value_or_default
("wiki.root_dir", "./").simplify_path
665 # Directory where markdown source files are stored.
667 # * key: `wiki.source_dir
668 # * default: `pages/`
669 var source_dir
: String is lazy
do
670 return value_or_default
("wiki.source_dir", "pages/").simplify_path
675 # Directory where public wiki files are generated.
676 # **This path MUST be relative to `root_dir`.**
678 # * key: `wiki.out_dir`
680 var out_dir
: String is lazy
do return value_or_default
("wiki.out_dir", "out/").simplify_path
682 # Asset files directory.
684 # Directory where public assets like JS scripts or CSS files are stored.
685 # **This path MUST be relative to `root_dir`.**
687 # * key: `wiki.assets_dir`
688 # * default: `assets/`
689 var assets_dir
: String is lazy
do
690 return value_or_default
("wiki.assets_dir", "assets/").simplify_path
693 # Template files directory.
695 # Directory where template used in HTML generation are stored.
696 # **This path MUST be relative to `root_dir`.**
698 # * key: `wiki.templates_dir`
699 # * default: `templates/`
700 var templates_dir
: String is lazy
do
701 return value_or_default
("wiki.templates_dir", "templates/").simplify_path
704 # Main template file.
706 # The main template is used to specify the overall structure of a page.
708 # * key: `wiki.template`
709 # * default: `template.html`
710 var template_file
: String is lazy
do
711 return value_or_default
("wiki.template", "template.html")
714 # Main header template file.
716 # Used to specify the structure of the page header.
717 # This is generally the place where you want to put your logo and wiki title.
719 # * key: `wiki.header`
720 # * default: `header.html`
721 var header_file
: String is lazy
do
722 return value_or_default
("wiki.header", "header.html")
725 # Main menu template file.
727 # Used to specify the menu structure.
730 # * default: `menu.html`
731 var menu_file
: String is lazy
do
732 return value_or_default
("wiki.menu", "menu.html")
737 # The main footer is used to specify the structure of the page footer.
738 # This is generally the place where you want to put your copyright.
740 # * key: `wiki.footer`
741 # * default: `footer.html`
742 var footer_file
: String is lazy
do
743 return value_or_default
("wiki.footer", "footer.html")
746 # Automatically add a summary.
748 # * key: `wiki.auto_summary`
750 var auto_summary
: Bool is lazy
do
751 return value_or_default
("wiki.auto_summary", "true") == "true"
754 # Automatically add breadcrumbs.
756 # * key: `wiki.auto_breadcrumbs`
758 var auto_breadcrumbs
: Bool is lazy
do
759 return value_or_default
("wiki.auto_breadcrumbs", "true") == "true"
764 # Position of the sidebar between `left`, `right` and `none`. Any other value
765 # will be considered as `none`.
767 # * key: `wiki.sidebar`
769 var sidebar
: String is lazy
do
770 return value_or_default
("wiki.sidebar", "left")
773 # Sidebar markdown block to include.
775 # Blocks are specified by their filename without the extension.
777 # * key: `wiki.sidebar.blocks`
779 var sidebar_blocks
: Array[String] is lazy
do
780 var res
= new Array[String]
781 if not has_key
("wiki.sidebar.blocks") then return res
782 for val
in at
("wiki.sidebar.blocks").as(not null).values
do
788 # Sidebar files directory.
790 # Directory where sidebar blocks are stored.
791 # **This path MUST be relative to `root_dir`.**
793 # * key: `wiki.sidebar_dir`
794 # * default: `sidebar/`
795 var sidebar_dir
: String is lazy
do
796 return value_or_default
("wiki.sidebar_dir", "sidebar/").simplify_path
799 # Directory used by rsync to upload wiki files.
801 # This information is used to update your distant wiki files (like the webserver).
803 # * key: `wiki.rsync_dir`
805 var rsync_dir
: String is lazy
do return value_or_default
("wiki.rsync_dir", "")
807 # Remote repository used to pull modifications on sources.
809 # * key: `wiki.git_origin`
810 # * default: `origin`
811 var git_origin
: String is lazy
do return value_or_default
("wiki.git_origin", "origin")
813 # Remote branch used to pull modifications on sources.
815 # * key: `wiki.git_branch`
816 # * default: `master`
817 var git_branch
: String is lazy
do return value_or_default
("wiki.git_branch", "master")
819 # URL to source versionning used to display last changes
821 # * key: `wiki.last_changes`
823 var last_changes
: String is lazy
do return value_or_default
("wiki.last_changes", "")
825 # URL to source edition.
829 var edit
: String is lazy
do return value_or_default
("wiki.edit", "")
832 # WikiSection custom configuration.
834 # Each section can provide its own config file to customize
835 # appearance or behavior.
839 # Returns the config value at `key` or `null` if no key was found.
840 private fun value_or_null
(key
: String): nullable String do
841 if not has_key
(key
) then return null
845 # Is this section hidden in sitemap and trees and menus?
846 fun is_hidden
: Bool do return value_or_null
("section.hidden") == "true"
848 # Custom section title if any.
849 fun title
: nullable String do return value_or_null
("section.title")
851 # Custom template file if any.
852 fun template_file
: nullable String do return value_or_null
("section.template")
854 # Custom header file if any.
855 fun header_file
: nullable String do return value_or_null
("section.header")
857 # Custom menu file if any.
858 fun menu_file
: nullable String do return value_or_null
("section.menu")
860 # Custom footer file if any.
861 fun footer_file
: nullable String do return value_or_null
("section.footer")