Add chapter for basic website setup

recoverysource · Aug 2, 2024 · 39490f1 · 39490f1
1 parent 4cb775f
commit 39490f1
Show file tree

Hide file tree

Showing 17 changed files with 112 additions and 16 deletions.
diff --git a/basic/website.rst b/basic/website.rst
@@ -3,10 +3,102 @@
 Very Basic Site
 ===============
 
-- Recap of Static vs. Dynamic w/ reference back to section in About Websites
-- Note that our project scope is static site generators due to total cost of ownership and long-term maintenance requirements
-- Recap of 2nd vs. 3rd-level domains
-- Recap how/why services like github provide free hosting for websites (using <3rd>.github.io)
-- We can use this "playground" repository to create an actual website.
-- Tutorial: Does github support creating a website directly from markdown files? We could create 2-3 additional pages and link to them.
-  The goal should be the minimum effort to get "Hello World" up on GitHub Pages.
+Although the ``index.html`` file from your :ref:`git repository <git-primer>`
+is not valid HTML, browsers will render basic text as a text file. This means
+that our existing ``git repo`` is already has everything needed to build a
+website.
+
+GitHub Pages
+------------
+
+To enabled ``GitHub Pages`` on this ``git repo``:
+
+1. Navigate to your git project on GitHub
+2. Click Settings (in the top menu)
+3. Click Pages (in the side menu)
+4. ``Source`` should already be set to ``Deploy from a branch``
+5. Change ``Branch`` to ``main/master``
+6. Click ``Save``
+7. Periodically refresh the page, until ``Your site is live`` shows up:
+
+.. image:: /static/images/basic/pages_setup.webp
+   :align: center
+   :width: 90%
+
+8. Click ``View site`` to see how a web browser will render your ``index.html``:
+
+.. image:: /static/images/basic/first_render.webp
+   :align: center
+
+Improving the Page
+------------------
+
+The page above is rendered from an ``index.html`` file that has only three lines
+of text. We now want to replace this content with a proper :ref:`HTML page
+<webpage>`.
+
+Replace the content of ``index.html`` with the following::
+
+    <!DOCTYPE html>
+    <html>
+    <head>
+      <title>Home Page | DemoSite</title>
+    </head>
+    <body>
+      <h1>Hello, World!</h1>
+      <p>This <b>bold</b> exists within paragraph tags.</p>
+    </body>
+    </html>
+
+Now create a high quality ``commit message`` and then ``push origin``. After a
+few moments, your website will now be updated with these changes.
+
+.. image:: /static/images/basic/second_render.webp
+   :align: center
+
+Second Page
+-----------
+
+With a valid ``index.html`` :ref:`HTML webpage <webpage>`, we can now create a
+second file, named ``second.html``::
+
+    <!DOCTYPE html>
+    <html>
+    <head>
+      <title>Second Page | DemoSite</title>
+    </head>
+    <body>
+      <h1>Page Number Two</h1>
+      <p>This is a second page <a href="/">with a link</a> to the Home page.</p>
+    </body>
+    </html>
+
+Add another set of paragraph tags to ``index.html`` with the following::
+
+      <p>Check out <a href="/second.html">Page #2</a></p>
+
+``GitHub Desktop`` should show the following ``diff``:
+
+.. image:: /static/images/basic/second_diff.webp
+   :align: center
+
+Push these changes to GitHub and wait for your website to be updated.
+
+Your website will now have two web pages with links back and forth!
+
+.. image:: /static/images/basic/second_page.webp
+   :align: center
+   :width: 90%
+
+.. _helloworld-recap:
+
+Chapter Recap
+-------------
+
+At this point, you have now created a ``Static Website`` and put it onto the
+:ref:`internet <internet>` using a :ref:`subdomain of github.io <fqdn>`
+(``<subdomain>.github.io``). A second page was added and then both linked to
+one another. You can even browse through each of these historical changes.
+
+The complexity of maintaining these links grows exponentially as websites grow. 
+Fortunately, :ref:`tools exist <jekyll>` to make this easier.
diff --git a/essentials/formats.rst b/essentials/formats.rst
@@ -181,3 +181,6 @@ Chapter Recap
 
 There are many :ref:`document formats <formats>` that are built from ``plain
 text`` files. Each have their own strengths, weaknesses, and use cases.
+
+In the next chapter, we will create a very basic ``static website`` using
+:ref:`HTML <html>`.
diff --git a/essentials/git.rst b/essentials/git.rst
@@ -16,7 +16,8 @@ Create a Repository
    :width: 90%
 
 2. For this demonstration, the repo ``Name`` should be your own username,
-   assuming it does not contain special characters.
+   assuming it does not contain special characters, with ``.github.io``
+   appended. So the user ``mtecknology`` should use ``mtecknology.github.io``.
 
 3. Putting something online does not make it :ref:`FOSS <def-foss>`; in order
    for others to (legally) download a copy, it **must** have a license that

diff --git a/index.rst b/index.rst
@@ -113,20 +113,20 @@ to help with maintenance tasks; our `Discord Link`_ is ``Open`` to all.
 .. toctree::
    :hidden:
    :includehidden:
-   :caption: Our Domain Solution
+   :caption: Your First Website
 
-   domain/about
-   domain/services
-   domain/address
-   domain/email
+   basic/website
+   basic/jekyll
 
 .. toctree::
    :hidden:
    :includehidden:
-   :caption: Your First Website
+   :caption: Our Domain Solution
 
-   basic/website
-   basic/jekyll
+   domain/about
+   domain/services
+   domain/address
+   domain/email
 
 .. toctree::
    :hidden:

diff --git a/static/images/basic/first_render.webp b/static/images/basic/first_render.webp
diff --git a/static/images/basic/pages_setup.webp b/static/images/basic/pages_setup.webp
diff --git a/static/images/basic/pages_setup.xcf b/static/images/basic/pages_setup.xcf
diff --git a/static/images/basic/second_diff.webp b/static/images/basic/second_diff.webp
diff --git a/static/images/basic/second_page.webp b/static/images/basic/second_page.webp
diff --git a/static/images/basic/second_page.xcf b/static/images/basic/second_page.xcf
diff --git a/static/images/basic/second_render.webp b/static/images/basic/second_render.webp
diff --git a/static/images/gitdesk/conflict_change2.webp b/static/images/gitdesk/conflict_change2.webp
diff --git a/static/images/gitdesk/first_push.webp b/static/images/gitdesk/first_push.webp
diff --git a/static/images/gitdesk/merge_conflicts.webp b/static/images/gitdesk/merge_conflicts.webp
diff --git a/static/images/gitdesk/new_file.webp b/static/images/gitdesk/new_file.webp
diff --git a/static/images/gitdesk/new_repo.webp b/static/images/gitdesk/new_repo.webp
diff --git a/static/images/gitdesk/newsite_commit.webp b/static/images/gitdesk/newsite_commit.webp