How can a Style Cell be safely programmatically appended to the Notebook Stylesheet at (Format -> Edit -> Stylesheet)

Question

The purpose of this is to append a DockedCell style definition to the list of cells inside Edit Stylesheet without deleting any existing style cells. My one attempt tends to erase existing private or custom style cells. More information can be found here: Cannot find DockedCells with Cells or NotebookFind

Answer 1

There is ResourceFunction["AddStyleToNotebook"] which allows to add a new style to the private stylesheet without erasing the existing styles. But unfortunately currently it has a bug specifically with the Initialization option. Hence until the bug isn't fixed we can define our own AddStyleToNotebook:

AddStyleToNotebook[nb_NotebookObject, cell_Cell] := 
 Module[{oldDefs = CurrentValue[nb, StyleDefinitions], newDefs},
  newDefs = If[Head[oldDefs] === Notebook,
    If[FreeQ[First@oldDefs, cell, {1}], Insert[oldDefs, cell, {1, -1}], oldDefs],
    Notebook[{Cell[StyleData[StyleDefinitions -> oldDefs]], cell}, 
     StyleDefinitions -> "PrivateStylesheetFormatting.nb"]];
  SetOptions[nb, StyleDefinitions -> newDefs]]

Use it as follows:

AddStyleToNotebook[EvaluationNotebook[], 
 Cell[StyleData["DockedCell"], 
  Initialization :> 
   If[Head[System`$DockedCells] === List, 
    System`$DockedCells = 
     Append[Select[System`$DockedCells, CurrentValue[#, CellID] =!= $Failed &], 
      EvaluationCell[]], System`$DockedCells = {EvaluationCell[]}]]]

(Here I put $DockedCells in the System` context in order to avoid namespace conflicts.)

---

My report about the bug in the current ResourceFunction["AddStyleToNotebook"]

Here, I'm including the report I just submitted using the "Submit a message about this function" button on the function's page:

Currently the resource function AddStyleToNotebook has a bug: when we try to add several times a new style containing the Initialization option, the latter will be damaged. As an example, consider the following use case:

ResourceFunction["AddStyleToNotebook"][EvaluationNotebook[], 
  "DockedCell", {Initialization :> 
    If[Head[System`$DockedCells] === List, 
     System`$DockedCells = 
      Append[Select[System`$DockedCells, CurrentValue[#, CellID] =!= $Failed &], 
       EvaluationCell[]], System`$DockedCells = {EvaluationCell[]}]}];

If we evaluate the above several times, we get a list of the above values as the value for the Initialization option, what is wrong and leads to the wrong behavior. The above definition is taken from the following answer where its purpose is explained:

https://mathematica.stackexchange.com/a/272038/280

Sincerely,
Alexey Popkov