Add option g:vimwiki_auto_header to automatically generate H1.

A level 1 header will automatically be generated for new files. The
title used in the header is based on the filename. Closes #245.

autoload/vimwiki/vars.vim

@@ -143,6 +143,7 @@ function! s:read_global_settings_from_user()
   let global_settings = {
         \ 'CJK_length': {'type': type(0), 'default': 0, 'min': 0, 'max': 1},
         \ 'auto_chdir': {'type': type(0), 'default': 0, 'min': 0, 'max': 1},
+        \ 'auto_header': {'type': type(0), 'default': 0, 'min': 0, 'max': 1},
         \ 'autowriteall': {'type': type(0), 'default': 1, 'min': 0, 'max': 1},
         \ 'conceallevel': {'type': type(0), 'default': 2, 'min': 0, 'max': 3},
         \ 'conceal_onechar_markers': {'type': type(0), 'default': 1, 'min': 0, 'max': 1},

doc/vimwiki.txt

@@ -3186,6 +3186,22 @@ values are from 0 to 2.
 The default is 1.
 
 
+------------------------------------------------------------------------------
+*g:vimwiki_auto_header*
+
+Set this option to 1 to automatically generate a level 1 header when creating
+a new wiki page. This option is disabled for the wiki index and the diary
+index. Spaces replaced with |vimwiki-option-links_space_char| are reverted
+back to spaces in the generated header, which will match the filename
+except for the characters that were reverted to spaces.
+
+For example, with `links_space_char` set to `'_'` creating a link from the text
+`foo bar link` would result in `[[foo_bar_link]]` and the file
+`foo_bar_link.wiki`. The generated header would be `= foo bar link =`
+
+The default is 0.
+
+
 ==============================================================================
 13. Getting help                                                *vimwiki-help*
 
@@ -3281,6 +3297,8 @@ https://github.com/vimwiki-backup/vimwiki/issues.
 2.5 (in progress)~
 
 New:~
+    * PR #661: Add option |g:vimwiki_auto_header| to automatically generate
+      a level 1 header for new wiki pages.
     * PR #665: Integration with vimwiki_markdown gem
       https://github.com/patrickdavey/vimwiki_markdown
       This provides the |vimwiki-option-html_filename_parameterization|

plugin/vimwiki.vim

@@ -239,6 +239,50 @@ if !exists("*VimwikiWikiIncludeHandler")
 endif
 
 
+" write a level 1 header to new wiki files
+" a:fname should be an absolute filepath
+function! s:create_h1(fname)
+  if vimwiki#vars#get_global('auto_header')
+    let idx = vimwiki#vars#get_bufferlocal('wiki_nr')
+
+    " don't do anything for unregistered wikis
+    if idx == -1
+      return
+    endif
+
+    " don't create header for the diary index page
+    if vimwiki#path#is_equal(a:fname,
+          \ vimwiki#vars#get_wikilocal('path', idx).vimwiki#vars#get_wikilocal('diary_rel_path', idx).
+          \ vimwiki#vars#get_wikilocal('diary_index', idx).vimwiki#vars#get_wikilocal('ext', idx))
+      return
+    endif
+
+    " get tail of filename without extension
+    let title = expand('%:t:r')
+
+    " don't insert header for index page
+    if title ==# vimwiki#vars#get_wikilocal('index', idx)
+      return
+    endif
+
+    " don't substitute space char for diary pages
+    if title !~# '^\d\{4}-\d\d-\d\d'
+      " NOTE: it is possible this could remove desired characters if the 'links_space_char'
+      " character matches characters that are intentionally used in the title.
+      let title = substitute(title, vimwiki#vars#get_wikilocal('links_space_char'), ' ', 'g')
+    endif
+
+    " insert the header
+    if vimwiki#vars#get_wikilocal('syntax') ==? 'markdown'
+      keepjumps call append(0, '# ' . title)
+      for _ in range(vimwiki#vars#get_global('markdown_header_style'))
+        keepjumps call append(1, '')
+      endfor
+    else
+      keepjumps call append(0, '= ' . title . ' =')
+    endif
+  endif
+endfunction
 
 " Define autocommands for all known wiki extensions
 
@@ -258,6 +302,8 @@ augroup vimwiki
     exe 'autocmd BufNewFile,BufRead *'.s:ext.' call s:setup_new_wiki_buffer()'
     exe 'autocmd BufEnter *'.s:ext.' call s:setup_buffer_enter()'
     exe 'autocmd BufLeave *'.s:ext.' call s:setup_buffer_leave()'
+    " automatically generate a level 1 header for new files
+    exe 'autocmd BufNewFile *'.s:ext.' call s:create_h1(expand("%:p"))'
     " Format tables when exit from insert mode. Do not use textwidth to
     " autowrap tables.
     if vimwiki#vars#get_global('table_auto_fmt')