Purpose

This article is related to web theme development with Hugo a static site generator.

When developing a more complex “shortcode” logic, in various cases it may be necessary to regenerate the repository of the website so that all changes are taken into account.

This requires stopping and restarting the running “hugo server” process.

Since this process can be tedious and repetitive, I created a batch script to automate this task and to save time.

image

A theme which supports local “file mode” ?

As of now and to my knowledge (which of course is limited) there are only a few themes which supports “file mode” out of the box.

If you need to build a documentation site, I highly recommend using the “Relearn theme” with the “Hugo static site generator.” Among its many outstanding features, this theme fully supports file mode, meaning no web server is required to access the website content.

Batch file

The following batch file can be used on Windows to start the website. During web development and article editing, I just wanted a simple solution to eliminate repetitive tasks.

  • Website development typically occurs locally using Hugo’s integrated web server.

  • Another possibility - which is fully supported by the Relearn theme - is to use the web site completely independent of any web server and in file mode only!

In practice, both modes need to be maintained and tested during site development.

My solution for this scenario is to use the batch file to streamline the process and get up and running quickly.

Commands which are currently provided by the batch script:

General:

  • [0] : Delete a running Web Server Process (if any…)

For Editing:

  • [1] Start or Restart Website Server (LIVE DEVELOPMENT)

    Use this for site editing, open a markdown file in the content directory, content will be life updated in the browser once a change is saved in the editor! Named Web server process already running will be automatically terminated.

  • [2] Compile Website (STANDALONE, NO SERVER REQUIRED)

    After compilation, just open the [site repository root directory]\index.html file.

For Viewing:

Preferred - use one of the following option to browse through the website. Note that the website is server-less, standalone and fully accessible via the file:// protocol. The powerful search engine is also supported in this mode.

  • [3] CHROME - Compile and Start Website (STATIC MODE)
  • [4] EDGE - Compile and Start Website (STATIC MODE)

Extras:

  • [X] Generate internal Website Docu (THE RELEARN HUGO THEME)

    After generation, open the file: [site repository root directory]\index.html to load the internal documentation which describes all available configuration options and shortcodes for managing the content.

  • [Y] Open the ‘RELEARN Theme Documentation’ directly with Chrome …

  • [V] Display Hugo Version…

  • [Q] Quit


Source code

At the beginning of the source code there is a configuration block which can be configured to meet a developers need. Please go through this section to see, whether there are adoptions to the configuration needed.

The batch file takes care of some of the basic command line arguments when starting the HUGO executable for various purposes.

Take a look at the source code...

@echo off
color F0

rem -----------------------------------------------------------------------------
rem --- Start-Documentation.bat
rem -----------------------------------------------------------------------------
rem (c) 2023, Johann Oberdorfer - Engineering Support | CAD | Software
rem     johann.oberdorfer [at] gmail [dot] com
rem     www.johann-oberdorfer.eu
rem -----------------------------------------------------------------------------
rem This source file is distributed under the BSD license.
rem   This program is distributed in the hope that it will be useful,
rem   but WITHOUT ANY WARRANTY; without even the implied warranty of
rem   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
rem   See the BSD License for more details.
rem -----------------------------------------------------------------------------
rem Revision history:
rem 2023-09-21 J.Oberdorfer, Initial Release
rem -----------------------------------------------------------------------------
rem
rem Problems encountered:
rem WARN 2023/09/19 20:02:40 "_index.md":
rem   DEPRECATED usage of old 'home' archetype found,
rem   add 'archetype="home"' to your frontmatter and remove the leading h1 heading; see
rem   https://mcshelby.github.io/hugo-theme-relearn/basics/migration/#500
rem Documentation:
rem   https://mcshelby.github.io/hugo-theme-relearn/basics/migration/index.html
rem -----------------------------------------------------------------------------

rem web development: some more ueful links:
rem Closing tag validator for html: https://www.aliciaramirez.com/closing-tags-checker/

call :colorEcho a0 "------------------------------"
call :colorEcho a0 "- Documentation Start Script -"
call :colorEcho a0 "------------------------------"
echo.

set CDIR=%CD%
set HUGO=".\themes\hugo.exe"
set HUGO1="C:\local\hugo.exe"
set DESTINATION=.\DOCUMENTATION-PUBLIC
set DOCUDESTINATION=..\DOCUMENTATION-PUBLIC-RELEARN-THEME

set BROWSER1="C:\Program Files (x86)\Google\Chrome\Application\chrome.exe"
set BROWSER2="C:\Program Files\Google\Chrome\Application\chrome.exe"

rem set CONTENTDIR=.\CONTENT
rem --contentDir %CONTENTDIR% argument is
rem not applicable, when set pdf's in index.files are not accessible due
rem to invalid path (hugo adds CONTENT to the path)

if exist %BROWSER1% (
	set BROWSER=%BROWSER1%
) else (
	if exist %BROWSER2% (
		set BROWSER=%BROWSER2%
	) else (
		echo.
		echo -------------------------------------------
		echo Error: BROWSER variable for Chrome not set!
		echo -------------------------------------------
		echo   Edit configuration in file:
		echo   %0%
		echo   and try again.
		echo -------------------------------------------
		echo.
		goto END1
	)
)

rem speed up in case we compile on a foreign machine, but like to
rem call-up the executable from local drive to save some band-width
if not exist "%HUGO%" ( set HUGO=%HUGO1% )

:SelectionMenu

echo Hugo executable set to: %HUGO%
echo.
echo Available Options
echo =================
echo.
echo.
echo [0] : Delete running Web Server Process (if any...)
echo.
echo     For Editing:
echo     ------------
echo     :
echo [1] : Start or Restart Website Server (LIVE DEVELOPMENT)
echo     : Use this for site editing, open a markdown file in the content directory,
echo     : content will be life updated in the browser once a change is saved in the editor!
echo     : Named Web server process already running will be automatically terminated.
echo     :
echo [2] : Compile Website (STANDALONE, NO SERVER REQUIRED)
echo     : After compilation, just open the file: %CDIR%\%DESTINATION%\index.html
echo.
echo     For Viewing:
echo     ------------
echo     : Preferred - use one of the following option to browse through the website.
echo     : Note that the website is server-less, standalone and fully accessible
echo     : via the file:// protocol. The powerful search engine is also supported in this mode.
echo     :
echo [3] : CHROME - Compile and Start Website (STATIC MODE)
echo [4] : EDGE   - Compile and Start Website (STATIC MODE)
echo.
echo     Extras:
echo     -------
echo     :
echo [X] : Generate internal Website Docu (THE RELEARN HUGO THEME)
echo     : After generation, open the file: %CDIR%\%DOCUDESTINATION%\index.html
echo     : to load the internal documentation which describes all available
echo     : configuration options and shortcodes for managing the content.
echo     :
echo [Y] : Open the 'RELEARN Theme Documentation' directly with Chrome ...
echo.
echo [V] : Display Hugo Version...
echo.
echo [Q] Quit
echo.
call :colorEcho a0 "================="
echo.

set usr=0
set /p usr="Please choose an option: "

if %usr%==0 goto Option0
if %usr%==1 goto Option1
if %usr%==2 goto Option2
if %usr%==3 goto Option3
if %usr%==4 goto Option4
if %usr%==x goto OptionX
if %usr%==X goto OptionX
if %usr%==y goto OptionY
if %usr%==Y goto OptionY
if %usr%==v goto OptionV
if %usr%==V goto OptionV
if %usr%==q goto END1
if %usr%==Q goto END1

cls & goto SelectionMenu

:Option0

for /f "tokens=2 delims=," %%a in ('
    tasklist /fi "imagename eq cmd.exe" /v /fo:csv /nh 
    ^| findstr -i  "Local-Web-Server"
') do taskkill /pid %%a

echo.
echo Web server processes cleanup done.
echo.

goto SelectionMenu

:Option1
cls

echo.
echo --------------------------------
echo 'Start Website Server' selected.
echo --------------------------------
echo.
echo Leave this window open during development.
echo Closing this window means that the development server process will be terminated.
echo.
echo Server is up and running,
echo please stand by, you browser (CHROME) will be continuously live-updated...
echo.
echo.

echo.
echo Attempt to delete any existing named web server process...
echo.

rem for /f "tokens=2" %%a in (`tasklist /v ^| findstr -i  "Local-Web-Server"`) do ...
rem https://stackoverflow.com/questions/26552368/
rem   windows-batch-file-taskkill-if-window-title-contains-text

for /f "tokens=2 delims=," %%a in ('
    tasklist /fi "imagename eq cmd.exe" /v /fo:csv /nh 
    ^| findstr -i  "Local-Web-Server"
') do taskkill /pid %%a

echo.
echo Web server processes cleanup done.
echo.

rem 1.) Required to run the browser *before hugo**.
rem     Seems that the browser automatically runs in background mode...

SET URL=" http:\\localhost:1313"
rem -disabled, previously used-
rem start /b %BROWSER% %URL%

start "" %BROWSER% %URL%
timeout 2 > NUL

rem 2.) execute hugo
rem     hugo does not want to run in background mode,
rem     that's why, we have to run hugo at the very end...

echo.
echo Executing:
echo %HUGO% --logLevel info --disableFastRender --cleanDestinationDir --noBuildLock ^
	--destination %DESTINATION% --watch server
echo.

rem start cmd /k ...
start /min "Local-Web-Server" cmd /c %HUGO% ^
	--logLevel info --disableFastRender --cleanDestinationDir --noBuildLock ^
	--destination %DESTINATION% --watch server

goto SelectionMenu

:Option2
cls

echo.
echo ---------------------------
echo 'Compile Website' selected.
echo ---------------------------
echo.

for /f "tokens=2 delims=," %%a in ('
    tasklist /fi "imagename eq cmd.exe" /v /fo:csv /nh 
    ^| findstr -i  "Local-Web-Server"
') do taskkill /pid %%a


%HUGO% --logLevel info --cleanDestinationDir --noBuildLock --minify ^
	--destination "%DESTINATION%"

goto SelectionMenu

:Option3
cls

echo.
echo -------------------------------------
echo 'Compile and Start Website' selected.
echo -------------------------------------
echo.

for /f "tokens=2 delims=," %%a in ('
    tasklist /fi "imagename eq cmd.exe" /v /fo:csv /nh 
    ^| findstr -i  "Local-Web-Server"
') do taskkill /pid %%a

set CDIR=%CD%
set URL="file://%CDIR%/%DESTINATION%/index.html"

rem --buildDrafts
rem --baseURL "/"
rem --forceSyncStatic

%HUGO% --logLevel info --cleanDestinationDir --noBuildLock --minify ^
	--destination "%DESTINATION%"
start "" %BROWSER% %URL%
rem start msedge %URL%

goto SelectionMenu

:Option4
cls

echo.
echo -------------------------------------
echo 'Compile and Start Website' selected.
echo -------------------------------------
echo.

for /f "tokens=2 delims=," %%a in ('
    tasklist /fi "imagename eq cmd.exe" /v /fo:csv /nh 
    ^| findstr -i  "Local-Web-Server"
') do taskkill /pid %%a

set CDIR=%CD%
set URL="file://%CDIR%/%DESTINATION%/index.html"

%HUGO% --logLevel info --cleanDestinationDir --noBuildLock --minify ^
	--destination %DESTINATION%
start msedge %URL%

goto END

:OptionX
cls

echo.
echo ------------------------------------------
echo 'Generate internal Website Docu' selected.
echo ------------------------------------------
echo.

rem note:
rem   the command line option for '--contentDir' will be superseded
rem   by the 'module mount' declaration rem in the config.yaml file, so we have to
rem   delete the module mount so that the following command will work...

set DOCUCONTENT="themes/hugo-theme-relearn-main/exampleSite/content"

%HUGO% ^
	--logLevel info ^
	--cleanDestinationDir --noBuildLock --minify ^
	--contentDir "%DOCUCONTENT%" ^
	--destination "%DOCUDESTINATION%"

goto END

:OptionY
cls

echo.
echo ------------------------------------------------
echo 'Open the RELEARN Theme Documentation' selected.
echo ------------------------------------------------
echo.

set URL="https://mcshelby.github.io/hugo-theme-relearn/basics/migration/index.html"
start "" %BROWSER% %URL%
rem start msedge %URL%

goto SelectionMenu

:OptionV
cls

echo.
echo.
echo Hugo executable set to: %HUGO%
%HUGO% version
echo.
echo.

pause

goto SelectionMenu

:END

echo.
echo -----------------
echo Command finished.
echo -----------------
echo.
pause

goto SelectionMenu

:END1

rem Cleaning up the web server process...

for /f "tokens=2 delims=," %%a in ('
    tasklist /fi "imagename eq cmd.exe" /v /fo:csv /nh 
    ^| findstr -i  "Local-Web-Server"
') do taskkill /pid %%a

echo.
echo ---------
echo Done now.
echo ---------
echo.

exit

:colorEcho
echo off
for /F "tokens=1,2 delims=#" %%a in ('"prompt #$H#$E# & echo on & for %%b in (1) do rem"') do (
  set "DEL=%%a"
)
<nul set /p ".=%DEL%" > "%~2"
findstr /v /a:%1 /R "^$" "%~2" nul
del "%~2" > nul 2>&1i
echo.
goto :eof

Download

File name:Size / byte:
Start-Documentation.zip3356

Credits: